# @sitebase/cli

The sitebase CLI is a tool for managing your standard.site data from the command line.

## Installation

```bash
# From the monorepo
bun install
bun run --filter @sitebase/cli build

# Link globally (optional)
bun link
```

## Setting the target publication

All commands except `auth *` and `pub list` require a target publication.

The target is determined from these sources, in order of precedence:

1. `--pub-id <rkey>` argument passed to the command
2. `.sitebase.json` file in the current directory with a `publicationId` property
3. `SITEBASE_PUB_ID` environment variable

The value is the **rkey** of the publication record (the last segment of the AT URI).

## Commands

### Auth

#### `auth login <handle>`

Logs in to an ATProto account via OAuth.

- Launches a temporary local HTTP server to handle the OAuth callback
- Opens your browser to the authorization page
- Requests the [standard.site auth bundle](https://pdsls.dev/at://did:plc:re3ebnp5v7ffagz6rb6xfei4/com.atproto.lexicon.schema/site.standard.authFull)
- Stores session data in `$HOME/.sitebase/session.json`

```bash
sitebase auth login <atproto-handle>
```

#### `auth logout`

Clears the stored session data.

```bash
sitebase auth logout
```

### Publication

#### `pub list`

Lists all publications in the authenticated account's PDS.

Does not require a target publication.

```bash
sitebase pub list
```

#### `pub set`

Interactively select a publication from your account to set as the target.

Writes the selection to `.sitebase.json` in the current directory.

```bash
sitebase pub set
```

#### `pub view`

Displays information about the target publication (name, URL, description, AT URI).

```bash
sitebase pub view # reads from SITEBASE_PUB_ID or .sitebase.json
sitebase pub view --pub-id my-blog
```

#### `pub edit`

Opens the publication metadata in `$EDITOR` for editing.

The publication data is presented as YAML. Save and close the editor to write changes back to the PDS.

```bash
sitebase pub edit
```

#### `pub export`

Exports all documents from the target publication to local files.

Uses a `sitebase.config.ts` configuration file. See [export.md](./export.md) for config format.

```bash
# Auto-discover sitebase.config.ts in current directory
sitebase pub export

# Specify config file
sitebase pub export --config ./my-config.ts
```

**Options:**

| Option | Description |
|--------|-------------|
| `-c, --config <file>` | Path to config file (auto-discovers `sitebase.config.ts` if not specified) |
| `--init` | Create a starter `sitebase.config.ts` and `templates/post.hbs` in the current directory |

```bash
# Initialize export config
sitebase pub export --init
```

### Documents

#### `doc list`

Lists all documents in the target publication.

```bash
sitebase doc list
sitebase doc list --tag post        # Filter by tag
sitebase doc list --tag draft       # Show drafts
```

#### `doc view <rkey>`

Displays a document's metadata and content preview.

```bash
sitebase doc view abc123
```

#### `doc edit <rkey>`

Opens a document in `$EDITOR` for editing.

The document is presented as a markdown file with YAML frontmatter (metadata in frontmatter, content in body). Save and close the editor to write changes back to the PDS.

**Content type restriction:** Only documents with `pub.sitebase.content.*` types can be edited. Documents with other content types (e.g., pckt.blog blocks) will show an error. Use `doc view` to inspect these documents instead.

```bash
sitebase doc edit abc123
```

#### `doc import <file>`

Creates a new document in the target publication from a local file.

The file should be markdown with YAML frontmatter containing at least a `title` field.

```bash
sitebase doc import ./my-post.md
sitebase doc import ./my-post.md --tag post --tag featured
```

#### `doc export <rkey>`

Exports a single document to a local file or stdout.

Unlike `pub export`, this command does NOT use the config file. Instead, options are provided via command line arguments.

```bash
# Output raw markdown to stdout
sitebase doc export abc123

# Output to file (filename supports handlebars)
sitebase doc export abc123 -o "{{publishedAt}}_{{slug title}}.md"

# With content template
sitebase doc export abc123 -t ./templates/post.hbs -o ./content/my-post.md
```

**Options:**

| Option | Description |
|--------|-------------|
| `-o, --output <file>` | Output filename (supports handlebars: `{{title}}`, `{{slug title}}`, `{{publishedAt}}`, etc.) |
| `-t, --template <file>` | Handlebars template file for content |
| `--stdout` | Output to stdout (default if no `-o`) |

### Drafts

Drafts are stored in a separate `pub.sitebase.draft` collection, not as `site.standard.document` records. This keeps unpublished work separate from your public documents.

See [lexicons.md](./lexicons.md) for the draft schema.

#### `draft list`

Lists all drafts for the target publication.

```bash
sitebase draft list
```

#### `draft new`

Creates a new draft and opens it in `$EDITOR`.

```bash
sitebase draft new
```

#### `draft edit <rkey>`

Opens a draft in `$EDITOR` for editing.

```bash
sitebase draft edit abc123
```

#### `draft publish <rkey>`

Publishes a draft as a `site.standard.document`.

- Creates a new document record with `publishedAt` set to current time
- Deletes the draft record

```bash
sitebase draft publish abc123
```

#### `draft delete <rkey>`

Deletes a draft without publishing.

```bash
sitebase draft delete abc123
```