> ## 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 the V3 API from local scripts with no API key.

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.

> [!NOTE]
>
> 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:

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

## 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\|admin` | The access to request. Repeat the option or list several values. The default is `read` and `write`. |
| `--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`, `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:

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

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

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](/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`.

## Where your sign-in is stored

The CLI and the SDK share one file:

| System | Path |
| - | - |
| macOS and Linux | `$XDG_CONFIG_HOME/apostra/credentials.json`, or `~/.config/apostra/credentials.json` |
| Windows | `%APPDATA%\apostra\credentials.json` |

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


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