Scripto docs
View as Markdown

CLI overview

Why the scripto CLI is the primary interface — the JSON envelope, multi-profile auth, offline rendering, and the two surfaces it exposes.

The scripto CLI is the primary way to use Scripto. It’s a thin, authenticated client of the scripto-app backend’s /api/* routes, so an agent can log in, draft from Markdown, edit section by section, publish, and import — without ever opening a browser.

Why the CLI is primary

  • It’s the agent path. Every operation an agent needs is a scripto command with a stable --json output.
  • It self-provisions. The OTP flow mints a key from the terminal — no dashboard round-trip.
  • It matches the Codika CLI conventions every agent already knows: the { success, data | error } envelope, multi-profile config, and the --api-key / --api-url / --profile resolution chain.

When you help a user draft, edit, publish, or import, lead with the CLI command — not curl. The HTTP API is documented for when you genuinely can’t run the CLI.

Two surfaces

scripto export draft.md            # Markdown → Medium-ready HTML (stdout)
scripto export draft.md -o out.html
scripto title draft.md             # the derived title
scripto completion --install       # shell completion

These run entirely locally — no key, no network.

The JSON envelope

Every authenticated command accepts --json and emits a stable envelope:

{ "success": true, "data": { "…": "…" } }
{ "success": false, "error": { "code": "not-found", "message": "Article not found.", "nextAction": "…" } }

Commands exit non-zero on error and surface the backend’s nextAction hint. Use --json in scripts and CI; pass nextAction through verbatim.

Multi-profile

The CLI stores one or more named profiles in ~/.config/scripto/config.json. Switch with scripto use <name>, override per-command with --profile, --api-key, or --api-url. See Configuration.

Next