@letterstory/cli weekly downloads statistics

@letterstory/cli

Spin up and manage Letter phantom blogs from your terminal. The CLI is a thin client over the Letter MCP endpoint (POST /api/mcp) — it wraps the same tool manifest an agent sees, so it never drifts from the API.

Install

The CLI is plain ESM with zero dependencies and needs no build step (Node ≥ 20).

npm install -g @letterstory/cli   # puts `letterstory` (and `phantom`) on your PATH
# …or run it without installing:
npx -p @letterstory/cli letterstory --help

The -p is not optional. This package ships two commands, letterstory and phantom, and npx only infers one for you when a package has a single command or one named after the package — neither is true here, so a bare npx @letterstory/cli exits with could not determine executable to run. Name the command you want (letterstory or phantom) and pass the package with -p.

Contributing to the CLI itself? Run it straight from a checkout instead:

cd cli
npm link          # puts `letterstory` (and `phantom`) on your PATH, pointing at this checkout
# …or run it directly without linking:
node cli/bin/letterstory.mjs --help

Updating

The CLI checks npm for a newer published version at most once every 24 hours (cached alongside your config, so most runs make no extra network call) and prints a one-line nudge on stderr when one's available:

Update available: 0.2.1 → 0.3.0. Run `npm install -g @letterstory/cli@latest` to upgrade.

To upgrade immediately:

npm install -g @letterstory/cli@latest

Set LETTERSTORY_NO_UPDATE_CHECK=1 to disable the check entirely (e.g. in CI).

phantom — the same CLI, Phantomstory-branded

phantom is a ghost-branded entry point for demos and presentations — same binary, same commands, same auth, same guardrails as letterstory, just a different printed name:

phantom deploy create --name "My Blog" --theme gazette
# 👻 phantom — deploy and manage Phantomstory blogs from your terminal

There is no separate implementation to keep in sync: bin/phantom.mjs sets one env var before importing lib/cli.mjs, which swaps the banner and command-hint strings and otherwise runs the exact same code path as letterstory.

Authenticate

Two ways in — pick whichever fits how you're running the CLI.

Sign in via your browser (the default — best for interactive use on your own machine):

letterstory login
# opens your browser to https://app.letterstory.com, or override with --url

This runs a browser-based OAuth 2.1 flow (PKCE, loopback redirect — RFC 8252) against your account. It comes back with a full-access session and a refresh token, so there's no API key to mint or scope up front. Tokens are saved to ~/.letterstory/config.json (mode 600) and refresh automatically. Run letterstory logout to revoke the session and forget it.

Or use a static API key (for CI/automation, or when you want scoped-down access):

You need a Letter API key (starts with ls_; legacy lb_ keys still work) with the phantom:read and phantom:write capabilities — mint one in the app under Settings → API keys (https://app.letterstory.com/settings?tab=api-keys). Add phantom:domain too if you plan to buy custom domains.

letterstory login --key ls_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# points at https://app.letterstory.com by default; override with --url

Credentials resolve from --key/--url flags, then LETTERSTORY_API_KEY / LETTERSTORY_API_URL, then ~/.letterstory/config.json (written by login, mode 600).

Run letterstory whoami (alias status) any time to confirm which key/url (or OAuth session) resolved and see your company profile. Run letterstory config to see the resolved url and credential source without making a network call.

Phantomstory — a collection Letter hosts as an independent publication

A phantom is a site we host that renders one of your collections; it never carries your company's name. Phantoms are metered in SITES live at once (phantom balance), not posts.

# provision a site and follow it until it's live (then it configures itself in the background:
# strategy, visuals, writing kernel, cadence, topic map)
letterstory phantom new --name "Saved Query" --config '{"cadence":{"posts_per_week":6}}'

#   Phantom 7c19c7… provisioning — following…
#     … provisioning · deploy
#     … provisioning · connect
#   Live at https://saved-query-7c19c7.letterstory-staging.com. Configuration continues in the background

letterstory phantom list
letterstory phantom get <phantom-id>
letterstory phantom config <phantom-id>                        # the site's file joined to its collection's
letterstory phantom config <phantom-id> --theme commons          # patch the site (identity/theme rebuild it)
letterstory phantom config <phantom-id> --collection-config '{"cadence":{"posts_per_week":4}}'
letterstory phantom config <phantom-id> --configure --dry-run   # what re-configuring would decide, applying nothing
letterstory phantom rebuild <phantom-id>                        # after publishing outside a collection run
letterstory phantom pause <phantom-id>                          # stop new posts and probing; the site stays live (resume to undo)
letterstory phantom resume <phantom-id>
letterstory phantom diagnostics <phantom-id>                    # why is my site empty?
letterstory phantom balance                                     # sites live / granted, and the cadence cap
letterstory phantom spread-looks [--apply]                      # a different look per site; dry run unless --apply
letterstory phantom delete <phantom-id> --yes

Pass --no-wait to return immediately and poll later with phantom get, --no-configure for a bare site, or --dry-run to see the plan without provisioning anything.…