> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Apostra CLI

> Sign in to Apostra from your terminal with `apostra login`, then call any public V3 operation with `apostra call` or from local scripts, with no API key.

The Apostra CLI signs you in through your browser and keeps the sign-in on your
machine. You can then call any public V3 operation from the terminal with
`apostra call`, and any Node.js script on that machine using `@apostra/sdk`
calls the V3 HTTP API as you, without an API key in your code or environment.
Use it for local development, shell scripts and agents. The CLI requires
Node.js 22.18 or later, and your scripts need `@apostra/sdk` 0.40.0 or later to
use the sign-in.

## Install

Run it without installing, or install it globally:

```bash theme={null}
npx @apostra/cli login
npm install --global @apostra/cli
```

The command is `apostra`. `apostra operations list` and
`apostra operations describe <operation>` show the public V3 operations.
With `--json`, `describe` also reports whether the operation is a write, which
needs an idempotency key, and the path and query parameters it takes.

## Sign in

```bash theme={null}
apostra login
```

The CLI opens your browser, you sign in to Apostra, and you approve access for
one account. When the browser shows that you are signed in, close the tab and
return to your terminal. If the CLI cannot open a browser, or you pass
`--no-browser`, it prints a URL to open yourself. Waiting for the browser
stops after 5 minutes.

| Option | What it does |
| - | - |
| `--account <id>` | Preselects that account on the approval screen. You still confirm it. |
| `--scope read\|write` | The access to request. Repeat the option or list several values. The default is `read` and `write`. Interactive sign-ins cannot request admin access. |
| `--base-url <url>` | The API to sign in to. The default is `https://api.apostra.com`, or `APOSTRA_BASE_URL` when it is set. |
| `--no-browser` | Print the sign-in URL instead of opening a browser. |

### One sign-in, one account

Each sign-in is bound to exactly one account: the one you approve in the
browser. It cannot reach your other accounts. To work in another account, run
`apostra login --account <id>` again; that replaces the stored sign-in for the
same API. You can only approve an account you are an active member of, and the
sign-in carries only the access you approved: `read` and `write` map to the
`interchange:read` and `interchange:write` permissions. Interactive sign-ins
cannot request admin access.

### How long it lasts

The access token lasts about one hour. The CLI and the SDK refresh it for you.
The sign-in itself stays valid for 30 days after its last refresh, so a script
you run at least monthly stays signed in. After that, or after you revoke it,
run `apostra login` again.

## Call any operation

```bash theme={null}
apostra call <operation> [--input <json> | @file.json | -] [--set path=value] \
  [--account <id>] [--idempotency-key <key>] [--all] [--json]
```

`apostra call` runs any public V3 operation by name, through the same
`@apostra/sdk` code your scripts use. The operation list comes from the SDK's
generated metadata, so an operation added to the SDK is callable as soon as the
CLI uses that SDK version, with no new CLI code. Run `apostra operations list` for the names.

```bash theme={null}
# Read the signed-in account's status
apostra call get_status

# Read delivery, with the request in a file
apostra call get_delivery --input @request.json --json

# The same request from stdin, with one field changed
cat request.json | apostra call get_delivery --input - --set limit=20 --json

# Page through every inventory source
apostra call search --set kind=inventory_source --set limit=50 --all --json

# A write: it needs an idempotency key
apostra call save_campaign --input @campaign.json --idempotency-key launch-2026-q4-1
```

| Option | What it does |
| - | - |
| `--input <json>` | The request body. Inline JSON, `@file.json` to read a file, or `-` to read stdin. It must be a JSON object. The default is `{}`. Parameters in the operation's path or query, such as a document ID, go in the same object. |
| `--set <path=value>` | Sets one field on top of `--input`. Repeat it for more fields. The value is read as JSON when it parses as JSON, otherwise as a string: `--set limit=20` sends a number, `--set kind=campaign` a string, `--set 'filter.status="active"'` a nested field. A dot makes a nested object; it cannot build arrays, so use `--input` for those. |
| `--account <id>` | The account this call runs in. See [Which account a call uses](https://docs.apostra.com/v3/cli.md#which-account-a-call-uses). |
| `--idempotency-key <key>` | Required for writes, refused for reads. Reuse the same key only to retry the same call. The CLI never makes one up, so a retry can never repeat a write. |
| `--all` | Follows `nextCursor` until the last page. See [Paging](https://docs.apostra.com/v3/cli.md#paging-with---all). Reads only. |
| `--max-pages <n>` | With `--all`, stop with an error after this many pages. The default is 100. |
| `--json` | Write the [JSON envelope](https://docs.apostra.com/v3/cli.md#json-output) instead of formatted JSON. |
| `--base-url <url>` | The API to call. The default is `https://api.apostra.com`, or `APOSTRA_BASE_URL` when it is set. |

Without `--json`, `call` prints the operation's result as formatted JSON.
`downloadV3PublicDocumentRevision` returns Markdown text; with `--json` it
arrives as `{"encoding": "utf-8", "content": "..."}` (`base64` if the bytes are
not valid UTF-8).

The CLI validates nothing about the request itself. The API checks the body
against the operation's contract and refuses what it cannot accept, and the CLI
reports that refusal with exit code 2. A write follows the same confirmation and
idempotency rules as the HTTP API.

### Which account a call uses

Every V3 call runs in one named account. `apostra call` picks it in this order
and prints the choice on stderr before it sends anything, for example
`Using account 42 (your sign-in).`:

1. `--account <id>`.
2. `APOSTRA_ACCOUNT_ID`.
3. The account your `apostra login` is bound to.

A sign-in reaches only the account you approved. If you name a different one,
the CLI stops with exit code 4 and sends nothing; run
`apostra login --account <id>` or use an API key. With an API key
(`APOSTRA_API_KEY`) there is no signed-in account, so you must name one with
`--account` or `APOSTRA_ACCOUNT_ID`. If the input also carries an `accountId`
that differs from the account the call runs in, the CLI refuses it the same way.

### Paging with `--all`

Some reads return one page and a `nextCursor`. With `--all`, `call` repeats the
request with each cursor until a response has none, and returns every page, in
order, as an array: `data` is `[page1, page2, ...]` and `meta.pages` is the
count. It sends your original request each time and changes only `cursor`.

`--all` never returns a partial result without saying so. It stops with an
error instead when:

* the response says there is more (`hasMore: true`) but gives no cursor
  (`INCOMPLETE_PAGINATION`, exit 6);
* the response holds more than one cursor, so it cannot tell which to follow
  (`AMBIGUOUS_PAGINATION`, exit 6);
* the API returns the same cursor twice (`PROTOCOL_ERROR`, exit 1);
* more pages remain after `--max-pages` (`PAGE_LIMIT`, exit 2).

An operation that does not page returns a single page, so `--all` is safe to
add to any JSON read. It is refused on writes.

## JSON output

Every command except `login` accepts `--json`. With it, stdout holds exactly
one line of JSON, and nothing else. Prompts, progress and diagnostics, including
the account line and the text of any error, go to stderr. An agent can pipe
stdout straight into a JSON parser.

A success:

```json theme={null}
{
  "schemaVersion": 1,
  "ok": true,
  "data": {},
  "meta": { "operation": "get_status", "accountId": "42", "requestId": "req_123" }
}
```

A failure, written to stdout as well, with the matching exit code:

```json theme={null}
{
  "schemaVersion": 1,
  "ok": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "This operation is not available to the selected account.",
    "exitCode": 4,
    "status": 403,
    "requestId": "req_123",
    "recovery": "correctable",
    "retryAfter": null
  }
}
```

| Field | Meaning |
| - | - |
| `schemaVersion` | The envelope version, `1`. It changes only for a breaking change to the envelope, never for a new field. Ignore fields you do not know. |
| `ok` | `true` with `data`, or `false` with `error`. Never both. |
| `data` | The command's result. For `call` it is the operation's `data` exactly as the API returned it, or the array of pages with `--all`. |
| `meta` | Present on `call`. `operation`, `accountId` (the account the call ran in), `requestId`, and with `--all` `pages` and `requestIds`. |
| `error.code` | A stable identifier to branch on. API errors keep the API's code. The CLI adds its own, such as `NOT_SIGNED_IN`, `ACCOUNT_REQUIRED`, `ACCOUNT_MISMATCH`, `UNKNOWN_OPERATION`, `IDEMPOTENCY_KEY_REQUIRED` and `INVALID_INPUT`. |
| `error.message` | A sentence for a person. For an API error it is the API's own message. Do not branch on it. |
| `error.exitCode` | The process exit code. |
| `error.status`, `requestId`, `recovery`, `retryAfter` | For API errors only: the HTTP status, the request ID to quote to support, whether a retry can help (`transient`, `correctable`, `terminal`), and the seconds to wait before retrying. |

The same envelope covers `operations list`, `operations describe`, `status`,
`token` and `logout`. `apostra token --json` returns the access token in
`data.token`, so treat that output as a password. `apostra login` is
interactive and has no JSON mode.

## Exit codes

| Code | Meaning | Examples |
| - | - | - |
| `0` | Success | |
| `1` | Server failure | A 5xx or 429 response, a timeout, a connection failure, an unexpected response. Often worth retrying; check `error.recovery`. |
| `2` | Invalid input | Bad JSON, an unknown operation or option, a missing idempotency key, a request the API refuses as invalid (400, 422), an object that does not exist (404). Fix the call and try again. |
| `3` | Authentication | Not signed in, an expired or revoked sign-in, a rejected API key (401). |
| `4` | Permission | The account is not reachable with this credential (403, `ACCOUNT_NOT_REACHABLE`), or you named an account other than the signed-in one. |
| `5` | Conflict | The API reports a conflict (409), or a write was accepted but has not settled yet (`IN_FLIGHT`). For `IN_FLIGHT`, repeat the same call with the same `--idempotency-key` to read the outcome. |
| `6` | Unavailable capability | The operation or feature is not available here (501, `NOT_IMPLEMENTED`, `FEATURE_NOT_ENABLED`), or `--all` cannot page safely. |

Exit codes never change meaning between releases. Help and `--version` exit `0`.
Running `apostra` with no command prints help and exits `2`.

## Use it from code

With no other credential set, the TypeScript SDK in Node.js and the Python SDK
use your sign-in for the API they are calling:

```typescript TypeScript theme={null}
import { Apostra } from '@apostra/sdk'

const api = new Apostra()
const status = await api.getStatus({})
```

```python Python theme={null}
from apostra import Apostra

api = Apostra()
status = api.get_status()
```

The SDKs never open a browser. If you set `accountId` (Python: `account_id`)
and it is not the account you signed in with, the SDK throws instead of
switching accounts. See [the credential
order](https://docs.apostra.com/v3/sdk-guide.md#credentials-and-accounts).

## Check, print and end a sign-in

```bash theme={null}
apostra status
apostra token
apostra logout
```

* `apostra status` shows the API, the bound account ID, the scopes and when the
  access token expires. It then reads the account's name and readiness from the
  API.
* `apostra token` prints a valid access token, refreshing it first when it is
  about to expire, and nothing else, so you can pipe it:
  `curl -H "Authorization: Bearer $(apostra token)" ...`. Treat the output as a
  password.
* `apostra logout` revokes the sign-in on the server and deletes it from your
  machine. If the server cannot be reached, the CLI still deletes the local
  copy and tells you the server-side sign-in was not revoked.

All three accept `--base-url` and `--json`.

## Where your sign-in is stored

The CLI and SDKs store each API sign-in in your operating system's
credential store:

| System | Store |
| - | - |
| macOS | Keychain |
| Windows | Credential Manager |
| Linux | Secret Service, such as GNOME Keyring or KWallet |

The entry contains the access token, refresh token, bound account and scopes.
It is named `Apostra CLI login` and is keyed by the exact API base URL, so
sign-ins for different APIs stay separate. Running `apostra logout` removes the
entry. When two processes need a refresh at once, one refreshes and the other
reuses the result across Node.js and Python processes.

On a machine without an available credential store, such as a headless Linux
host, Apostra falls back to `$XDG_CONFIG_HOME/apostra/credentials.json` (or
`~/.config/apostra/credentials.json`; `%APPDATA%\apostra\credentials.json` on
Windows). It prints a one-time warning and creates the folder with mode 0700
and the file with mode 0600. Anyone who can read that file can act as you, so
do not copy it, commit it, or mount it into a shared container. When you next
run on a machine with a credential store, Apostra migrates every valid entry
from that file and deletes the file.

## Continuous integration and servers

Do not use `apostra login` in CI, in a container, or on a server. It needs a
browser and a person. Create an [API key or M2M access
token](https://docs.apostra.com/v3/http-api.md#make-a-request) for the account and pass it through your
secret manager. When `APOSTRA_API_KEY` is set, the SDK and `apostra call` use it
and ignore any sign-in on the machine. `apostra call` also needs the account:
set `APOSTRA_ACCOUNT_ID` or pass `--account`.

```bash theme={null}
APOSTRA_API_KEY=... apostra call get_status --account 42 --json
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.