seth.computer / sitebase
this repo has no description
fork atom
sitebase / docs / cli.md
at design-docs 5.5 kB view raw view code
seth.computer CLI docs, needs some iteration, but covers the commands
1d924c17

@sitebase/cli#

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

Installation#

# 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
  • Stores session data in $HOME/.sitebase/session.json
sitebase auth login <atproto-handle>

auth logout#

Clears the stored session data.

sitebase auth logout

Publication#

pub list#

Lists all publications in the authenticated account's PDS.

Does not require a target publication.

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.

sitebase pub set

pub view#

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

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.

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 for config format.

# 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 
# Initialize export config
sitebase pub export --init

Documents#

doc list#

Lists all documents in the target publication.

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.

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.

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.

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.

# 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 for the draft schema.

draft list#

Lists all drafts for the target publication.

sitebase draft list

draft new#

Creates a new draft and opens it in $EDITOR.

sitebase draft new

draft edit <rkey>#

Opens a draft in $EDITOR for editing.

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
sitebase draft publish abc123

draft delete <rkey>#

Deletes a draft without publishing.

sitebase draft delete abc123