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: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
--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, runapostra 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, runapostra 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).:
--account <id>.APOSTRA_ACCOUNT_ID.- The account your
apostra loginis bound to.
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).
--all is safe to
add to any JSON read. It is refused on writes.
JSON output
Every command exceptlogin 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:
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: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 statusshows 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 tokenprints 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 logoutrevokes 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.
--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 useapostra 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.