Skip to main content
The Apostra CLI signs you in through your browser and keeps the sign-in on your machine. Any script on that machine that uses @apostra/sdk in Node.js then calls the V3 HTTP API as you, without an API key in your code or environment. Use it for local development. It requires Node.js 22.18 or later.
The Apostra CLI is not on npm yet, and the @apostra/sdk version that uses its sign-in has not been released. Until both are published, npx @apostra/cli and npm install --global @apostra/cli cannot find the package, so use an API key or an M2M credential. The server side of apostra login is already live.

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

​
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, write and admin map to the interchange:read, interchange:write and interchange:admin permissions. Ask for admin only when you need it.

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

​
Use it from code

With no other credential set, the TypeScript SDK in Node.js uses your sign-in for the API it is calling:
The SDK never opens a browser. If you set accountId 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.

​
Where your sign-in is stored

The CLI and the SDK share one file: The file holds one entry for each API you signed in to, with the access token, the refresh token, the bound account and the scopes. Only your user can read it: the folder is created with mode 0700 and the file with mode 0600. Anyone who can read that file can act as you in that account, so do not copy it, commit it, or mount it into a shared container. Running apostra logout removes the entry. When two processes need a refresh at once, one refreshes and the other reuses the result.

​
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 uses it and ignores any sign-in on the machine.