---
title: CLI overview
description: 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](https://www.npmjs.com/package/@codika-io/scripto) 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.

<Note>

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.

</Note>

## Two surfaces

<Tabs>

<Tab label="Offline (no network)">

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

</Tab>

<Tab label="Authenticated">

```bash
scripto auth login-request --email you@example.com
scripto auth login-complete --email you@example.com --code 123456
scripto whoami
scripto articles create --file draft.md
scripto articles publish <id>
```

These talk to the backend over your `scripto_` key.

</Tab>

</Tabs>

## The JSON envelope

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

```json
{ "success": true, "data": { "…": "…" } }
```

```json
{ "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](/cli/configuration).

## Next

- **[Installation](/cli/installation)** — `npm install -g @codika-io/scripto`.
- **[Auth (OTP login)](/cli/auth)** — the OTP flow in detail.
- **[Command reference](/cli/commands)** — every command and flag.