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

# CLI

> basaltic, the command-line interface to the platform.

`basaltic` is the command-line client. It signs every request for you, so it is
the shortest path to driving the platform from a terminal or a CI job.

<Note>
  The CLI is not yet published to a package manager or a downloads page. If you
  need it today, ask us through [support](/support) and we will get you a build.
</Note>

## Command shape

Commands follow the resources of the API:

```
basaltic <category> <resource> <action> [flags]
```

```bash theme={null}
basaltic compute instances list
basaltic compute instances get <instance-id>
basaltic compute instances create --name web-1 --flavor <flavor-id>
basaltic storage volumes list
basaltic dns zones list
```

The tree is derived from the API specification itself, so it stays in step with
the platform — a new endpoint becomes a new subcommand rather than waiting on a
hand-written wrapper. `basaltic --help` lists the categories;
`basaltic <category> --help` and `basaltic <category> <resource> --help` walk
down from there.

## Authenticating

Credentials live in a **profile** in `~/.config/basaltic/config.yaml`. Sign in
once and the CLI persists them:

```bash theme={null}
basaltic auth login      # browser-based sign-in
basaltic auth status     # active profile, key id, region
basaltic auth logout     # clear the active profile's credentials
```

To use an access key from a [service account](/authentication#getting-credentials)
instead — the right choice for CI — set it on a profile:

```bash theme={null}
basaltic config set <profile>.api_key <ACCESS_KEY_ID>:<SECRET_ACCESS_KEY>
basaltic config set <profile>.region sa-saopaulo-1
```

Then select it per command with `--profile`, or leave it as the default.

<Tip>
  Prefer a profile over passing `--api-key` on each invocation. The flag puts
  the secret in your shell history and in the process list of every user on the
  machine.
</Tip>

## Global flags

| Flag            | Purpose                                                      |
| --------------- | ------------------------------------------------------------ |
| `-p, --profile` | Use a specific profile from the config                       |
| `-r, --region`  | Target region, e.g. `sa-saopaulo-1`                          |
| `-o, --output`  | Output format: `text`, `json`, or `yaml`                     |
| `--account-id`  | Act against another account you have access to               |
| `--api-key`     | `ACCESS_KEY_ID:SECRET_ACCESS_KEY`, overriding env and config |
| `-v, --verbose` | Log HTTP requests and responses to stderr                    |

`--output json` is the one to reach for in scripts; `-v` is the one to reach for
when a call is failing and you want to see what actually went over the wire.

## Configuration

```bash theme={null}
basaltic config list           # dump the current configuration
basaltic config get <key>      # print one value
basaltic config set <key> <value>
```

The file is `~/.config/basaltic/config.yaml`, honoring `XDG_CONFIG_HOME`.

## Container registry login

The registry mints a short-lived credential that `docker login` consumes. The
username is fixed — the token is what identifies you:

```bash theme={null}
basaltic authorization authorization-token --output json \
  | jq -r .authorization_data.password \
  | docker login --username basaltic --password-stdin \
      registry.sa-saopaulo-1.basaltic.sh
```

The credential names no repository and grants no access on its own. The docker
daemon exchanges it for per-repository tokens, and every authorization decision
is made at that point against your policies as they stand.