@slices/cli#

A command-line interface for managing slice instances and AT Protocol lexicons on https://slices.network.

Features#

Lexicon Management - Push, pull, and list lexicon files in your slices
Code Generation - Generate TypeScript clients from lexicons
Project Scaffolding - Initialize new Deno SSR projects with OAuth
Project Configuration - Optional slices.json config file support

Installation#

# Install globally from JSR
deno install -g -A jsr:@slices/cli --name slices

# Or run directly
deno run -A jsr:@slices/cli [command]

Quick Start#

Authenticate with Slices
```
slices login
```
Initialize a new project
```
slices init my-project
```
Push lexicon files to your slice
```
slices lexicon push
```

Commands#

`slices login`#

Authenticate with Slices.

slices login [OPTIONS]

OPTIONS:
    --aip-url <URL>        AIP server base URL (default: https://auth.slices.network)
    --client-id <ID>       OAuth client ID (default: slices-cli)
    --scope <SCOPE>        OAuth scope (default: atproto:atproto)
    --force               Force login even if already authenticated
    -h, --help            Show help

Example:

# Basic login
slices login

# Force re-authentication
slices login --force

# Use custom AIP server
slices login --aip-url https://custom-aip.example.com

`slices lexicon push`#

Push lexicon files to your slice with automatic validation.

slices lexicon push [OPTIONS]

OPTIONS:
    --path <PATH>          Directory containing lexicon files (default: ./lexicons or from slices.json)
    --slice <SLICE_URI>    Target slice URI (required, or from slices.json)
    --exclude-from-sync    Exclude these lexicons from sync (sets excludedFromSync: true)
    --validate-only        Only validate files, don't upload
    --dry-run             Show what would be pushed without uploading
    --api-url <URL>       Slices API base URL (default: https://api.slices.network or from slices.json)
    -h, --help            Show help

`slices lexicon pull`#

Pull lexicon files from your slice.

slices lexicon pull [OPTIONS]

OPTIONS:
    --path <PATH>          Directory to save lexicon files (default: ./lexicons or from slices.json)
    --slice <SLICE_URI>    Source slice URI (required, or from slices.json)
    --nsid <PATTERN>      Filter lexicons by NSID pattern (supports wildcards with *)
    --api-url <URL>       Slices API base URL (default: https://api.slices.network or from slices.json)
    -h, --help            Show help

`slices lexicon list`#

List all lexicons in your slice.

slices lexicon list [OPTIONS]

OPTIONS:
    --slice <SLICE_URI>    Target slice URI (required, or from slices.json)
    --api-url <URL>        Slices API base URL (default: https://api.slices.network or from slices.json)
    -h, --help            Show help

`slices init`#

Initialize a new Deno SSR project with OAuth authentication.

slices init <project-name>
slices init --name <project-name>

OPTIONS:
    -n, --name <name>    Project name
    -h, --help          Show help

`slices status`#

Show authentication and configuration status.

slices status [OPTIONS]

OPTIONS:
    -h, --help            Show help

`slices logs`#

View Jetstream logs for a slice.

slices logs [OPTIONS]

OPTIONS:
    --slice <SLICE_URI>    Target slice URI (optional, or from slices.json)
    --limit <NUMBER>       Maximum number of log entries to return (default: 100, max: 1000)
    --api-url <URL>        Slices API base URL (default: https://api.slices.network or from slices.json)
    -h, --help             Show help

`slices codegen`#

Generate TypeScript client from lexicon files.

slices codegen [OPTIONS]

OPTIONS:
    --lexicons <PATH>      Directory containing lexicon files (default: ./lexicons or from slices.json)
    --output <PATH>        Output file path (default: ./generated_client.ts or from slices.json)
    --slice <SLICE_URI>    Target slice URI (required, or from slices.json)
    --exclude-slices       Exclude @slices/client integration
    -h, --help            Show help

Examples:

# Push all lexicons from ./lexicons (using slices.json config)
slices lexicon push

# Push from custom directory
slices lexicon push --path ./my-lexicons --slice at://did:plc:example/slice

# Validate only (no upload)
slices lexicon push --validate-only --path ./lexicons

# Dry run (see what would be pushed)
slices lexicon push --dry-run

# Pull lexicons from slice
slices lexicon pull

# List lexicons in slice
slices lexicon list

# Generate TypeScript client
slices codegen

# Initialize new project
slices init my-project

# View slice logs
slices logs --slice at://did:plc:example/slice

Global Options#

-v, --verbose - Enable verbose logging
--version - Show version information
-h, --help - Show help

Configuration#

CLI Configuration#

The CLI stores configuration in ~/.config/slices/config.json.

Config structure:

{
  "auth": {
    "accessToken": "...",
    "refreshToken": "...",
    "expiresAt": 1234567890000,
    "did": "did:plc:example",
    "aipBaseUrl": "https://auth.slices.network"
  }
}

Project Config#

Create a slices.json file in your project root to avoid passing common options every time:

{
  "slice": "at://did:plc:example/slice",
  "lexiconPath": "./lexicons",
  "clientOutputPath": "./generated_client.ts",
  "apiUrl": "https://api.slices.network"
}

Config options:

slice - Your slice URI (used by lexicon push, lexicon pull, lexicon list, codegen)
lexiconPath - Directory containing lexicon files (default: ./lexicons)
clientOutputPath - Output path for generated TypeScript client (default: ./generated_client.ts)
apiUrl - Slices API base URL (default: https://api.slices.network)

The CLI will search for slices.json starting from the current directory and walking up the directory tree. Command line arguments always take precedence over config file values.

Lexicon File Requirements#

Lexicon files must be valid JSON files with the following structure. For the full specification, see https://atproto.com/specs/lexicon.

{
  "id": "com.example.post",
  "definitions": {
    "main": {
      "type": "record",
      "properties": {
        "text": { "type": "string" },
        "createdAt": { "type": "string", "format": "datetime" }
      },
      "required": ["text", "createdAt"]
    }
  }
}

The CLI will:

Scan the specified directory for .json files
Validate each file using @slices/lexicon
Report validation errors with specific feedback
Upload only valid lexicons to your slice

Development#

# Run from source
deno run --allow-all src/mod.ts [command]

# Build executable
deno task build

# Run tests
deno task test

Error Handling#

The CLI provides detailed error messages and suggestions:

Login errors - Prompts to run slices login
Validation errors - Shows specific issues with lexicon files
Network errors - Displays connection and API errors
File errors - Reports missing files or invalid JSON

Examples#

Complete Workflow#

# 1. Authenticate
slices login

# 2. Initialize project
slices init awesome-slice

# 3. Validate lexicons first
slices lexicon push --validate-only

# 4. Push to slice
slices lexicon push

# 5. Generate TypeScript client
slices codegen

# 6. List lexicons
slices lexicon list

License#

MIT