Skip to main content
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:
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

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.

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

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.
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:
A failure, written to stdout as well, with the matching exit code:
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

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:
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.

Check, print and end a sign-in

  • 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: 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 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.