CLI

aura administers Aura from a terminal: deploy a model, manage projects and conversations, and chat with a project to try it out.

For behaviour you ship in software, use the SDKs — the CLI is built on the TypeScript one, so anything it does is a library call too. What it prints is written for a person to read, not to be parsed: aura project create announces the new project rather than emitting a bare id. When you need a field as data, an error you can branch on, or a turn as it streams, that is the SDKs’ job.

Install

npm install -g @strangeworks-inc/strangeworks-aura-cli
export AURA_API_KEY="sk-aura-..."
aura --help

The key is the only thing you have to supply: mint one at Settings → API Keys in the Aura web app (see Authentication). Commands talk to the EU deployment, https://aura-api-eu.strangeworks.com, unless you point them somewhere else — a key minted in the US app needs --region us.

aura --version prints the installed version — useful when checking an upgrade landed.

Shell completion

aura completion prints a completion script for your shell. The shell is detected from $SHELL unless you name one (bash, zsh, fish).

echo 'eval "$(aura completion)"' >> ~/.zshrc    # or ~/.bashrc

Fish keeps completions in a directory instead:

aura completion fish > ~/.config/fish/completions/aura.fish

The script is a stub that asks aura what completes where you are, so it never goes stale — commands added by an upgrade complete immediately, with no need to re-run this. Commands, subcommands and flags are completed, and a flag you have already passed stops being offered. Values — project ids, deployment handles — are not: that would need an authenticated API call on every Tab.

zsh: load it after compinit

compdef only exists once compinit has run, so the eval has to come after it in your .zshrc. Loaded too early, the completion tells you so rather than failing silently.

Configure

Settings resolve flag → environment → config file → default, and aura config shows each value next to where it came from — which is the answer to “why is it still talking to staging?”.

export AURA_API_KEY="sk-aura-..."
aura config set region us                        # the US deployment
aura config set base_url http://localhost:3000   # or any other Aura
aura config                                      # every setting, its value, and its source

base_url defaults to the host of whichever region is in effect — https://aura-api-eu.strangeworks.com unless you set one — so leave both alone unless you are on the US deployment (region) or a development stack (base_url). base_url wins over region wherever both are set, and aura config reports each value’s source, so region under base_url means a region chose the host and default means nothing of yours did. See Regions.

The API key has no default, and is the one setting whose absence stops a command:

error No API key.

Set AURA_API_KEY in your environment, or pass --api-key — a company key (sk-aura-…).
It is never read from the config file.

A host that is configured but does not answer is a different failure, and says so — naming the host it tried and the reason the OS gave:

error Could not reach http://localhost:3000 (ECONNREFUSED)
Check that the server is running and that AURA_BASE_URL (or --base-url) points at it.

A rejected request is a third: there the first line is the API’s own explanation, with the fix under it where the CLI knows one. Errors covers all three.

`echo` is not the same test as the CLI

echo $AURA_API_KEY prints a shell variable whether or not it was exported; a command only inherits exported ones. If the CLI says the key is not set while echo shows it, check with printenv AURA_API_KEY — empty output means you need export AURA_API_KEY=….

The config file is TOML, at ~/.config/aura/config.toml ($XDG_CONFIG_HOME and $AURA_CONFIG are honoured; Windows uses %APPDATA%\aura\).

~/.config/aura/config.toml

base_url   = "http://localhost:3000"   # http or https, validated when written; omit for production
region     = "us"        # eu | us (AURA_REGION); base_url wins when both are set
project    = "5c506a0f-…"  # the project commands act on (AURA_PROJECT)
theme      = "auto"      # auto | dark | light (AURA_THEME)
full_dates = false       # true to show exact timestamps everywhere (AURA_FULL_DATES)

The file is per user, not per directory — one selected project per machine, with AURA_PROJECT for one shell and --project for one command. A file that cannot be read or written is reported rather than treated as empty, and the message names the manual route: a command you gave --project runs regardless, because it never needed the file.

Every command takes --base-url / --region / --api-key except aura init, aura config, aura completion and aura skill install, which are offline.

aura config path prints the location. A key comes from Authentication — the web app’s settings, shown once at creation.

The API key is not a config-file setting

api_key is rejected in the file, by name and with a reason. A plaintext sk-aura-… in a dotfile is the credential that ends up in a backup, a sync folder or a commit — so it comes from AURA_API_KEY or --api-key. aura config does not list it at all: it is not a setting, and a row for it would suggest the file is somewhere it could be put.

Choosing the project

Most commands act on one project. Rather than naming it every time, select it once:

aura project use 5c506a0f-1d3e-4b8a-9f21-7c0e4a2b6d15
aura project current             # which one, and where that came from
aura chat                        # no flag needed

aura project create selects the project it creates, so the id it prints does not have to be pasted into the next command. --no-select leaves the current selection alone.

The project resolves like every other setting — --project → AURA_PROJECT → the config file:

aura snapshot list --project <other-id>       # one command, one project
AURA_PROJECT=<other-id> aura snapshot list    # one shell, or a CI job

aura project current --id prints the bare id and makes no request, for $(…) in a script. Both forms fail when nothing is selected, so --id doubles as a guard. With nothing selected, any command that needs one says so and names all three ways to give it:

error No project selected.

Run "aura project use <id>", set AURA_PROJECT, or pass --project.
"aura project list" shows them.

Light and dark terminals

Help and error messages use your terminal’s own colours, so they follow whatever theme you run and need no setting.

Everything a command produces — listings, tables, deploy progress — and the chat UI use Aura’s palette, which is tuned for a dark background. theme = "light" (or AURA_THEME=light) switches those to variants darkened until they read on white.

auto, the default, reads COLORFGBG when your terminal sets it and assumes dark otherwise. It deliberately does not ask the terminal for its background colour: that needs a raw-mode reply on stdin, which is a round-trip on every command and has bitten this CLI before. If auto guesses wrong, set the theme explicitly — it is one line and it is reliable.

The usual loop

1. Describe the deployment once, in your model folder’s pyproject.toml:

   cd my-model/solver
   aura init

   pyproject.toml

   [tool.aura.deployment.vrp]
   model_folder = "."
   data_folder  = "../define/data"
   include      = ["pyproject.toml", "run.py", "src/solver/**"]

2. Preview, then deploy:

   aura deploy --dry-run
   aura deploy
   aura deployment check

3. Create a project from it:

   aura project create acme/vrp --name "vrp demo"

4. Chat. project create selected the project, so this needs no id:

   aura chat

How commands are shaped

Verbs live under the noun they act on, and the noun that owns sub-resources nests one level further:

aura deployment list
aura deployment skills list
aura project skills show depot-handover

deploy and chat stay top-level — they are the daily verbs, and deploy reads a config table rather than acting on a named deployment.

Three rules hold throughout:

• A positional is the operand — the thing the verb acts on. aura snapshot file read <ref> <path> reads that path in that snapshot; aura project delete <id> deletes that project.
• Context is a flag. Where the project is not the operand but the place the operand lives, it is --project, and it defaults to the selected project. So the project is a positional in aura project delete <id>, where it is what gets deleted, and a flag in aura project checkout <ref>, where the ref is.
• A deployment name is a trailing positional, optional where a config table can supply it.

No command takes two positionals of the same shape, so there is never a pair of ids whose order you have to remember.

The noun decides what a command can change

aura deployment … changes the deployment, so every project created from it afterwards starts with the result. aura project … changes that project alone and can never reach the deployment or a sibling.

aura, or aura <noun> on its own, lists what is there. --help works at every level, and a mistyped command or flag is answered with the nearest real one rather than a stack trace.

Reading a listing

Listings are tables with a blank line around them and a count underneath. Text columns are elided to fit the terminal; ids and handles never are, because they exist to be pasted into the next command.

Timestamps are relative — 3h ago. Pass --full-dates for the exact value.

Exit codes

Code	Means
0	Success
1	An API or usage error, printed as a plain message
130	Ctrl-C during a turn — the turn was cancelled server-side too

Next

Init & configDeclare a deployment in pyproject.toml.

SkillLet your coding agent drive Aura for you.

DeploymentDeploy, then manage what it ships.

ProjectCreate a project and configure its agent.

SnapshotList, read, and tag a project's snapshots.

WorkspaceList, read, write, and delete live workspace files.

ConversationList and delete a project's threads.

Chat sessionKeys, slash commands, and quick replies.

DashboardOpen a project's run dashboard in a browser.

UsageRead your company's usage in credits.