# @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

```bash
# 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

1. **Authenticate with Slices**
   ```bash
   slices login
   ```

2. **Initialize a new project**
   ```bash
   slices init my-project
   ```

3. **Push lexicon files to your slice**
   ```bash
   slices lexicon push
   ```

## Commands

### `slices login`

Authenticate with Slices.

```bash
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:**

```bash
# 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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
slices status [OPTIONS]

OPTIONS:
    -h, --help            Show help
```

### `slices logs`

View Jetstream logs for a slice.

```bash
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.

```bash
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:**

```bash
# 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:**

```json
{
  "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:

```json
{
  "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.

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

The CLI will:

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

## Development

```bash
# 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

```bash
# 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