CLI

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

Chatting from the CLI is for trying a deployment out — checking the model solves what you meant and the data is right. To put that behaviour in software you ship, use the SDKs.

The CLI is built on the TypeScript SDK, so anything it does is available as a library call.

Install

npm install -g @strangeworks/aura-cli

aura --help

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 base_url https://aura.strangeworks.com
aura config                       # every setting, its value, and its source

If a command cannot connect it names exactly which setting is missing, and only that one:

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.

`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   = "https://aura.strangeworks.com"   # http or https, validated when written
theme      = "auto"      # auto | dark | light (AURA_THEME)
full_dates = false       # true to show exact timestamps everywhere (AURA_FULL_DATES)

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

aura config path prints the location. A key comes from Authentication — company settings in the web app, 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.

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:

   aura chat --project <project-id>

Command layout

Operations on a noun are grouped under it — aura deployment …, aura project …, aura conversation …. deploy and chat stay top-level; deploy reads a manifest rather than acting on a named deployment.

aura deployment list
aura project list
aura conversation list --project <project-id>

A parent project is always a --project <id> flag, never a positional.

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.

Listings show relative timestamps — 3h ago. Pass --full-dates for the exact value.

Scripting it

--message skips the interactive UI: one reply to stdout, non-zero exit on API errors.

#!/usr/bin/env bash
set -euo pipefail

aura chat --project "$AURA_PROJECT" \
  --message "Solve with tonight's data and report the objective." \
  > nightly-report.md

The other commands print for a human to read: aura project create announces the new project rather than emitting a bare id. For a pipeline that needs the id, use the SDK rather than parsing CLI output.

Ctrl-C stops the turn, not just the CLI

Interrupting --message cancels the turn server-side and exits 130. Otherwise the turn would run to completion after you left.

The interactive TUI

aura chat --project <id> without --message opens a full-screen terminal UI — pinned header, scrolling transcript, composer at the bottom. It uses the alternate screen buffer, so your shell’s scrollback is untouched, and prints the resume command on exit.

The basics, with the full list in the reference:

• enter sends, shift+enter (or alt+enter) makes a newline.
• esc cancels a running turn and keeps you in the session.
• Typing / opens the command menu: keep typing to narrow it, ↑/↓ to move, tab to fill the name in, enter to run it, esc to dismiss. A leading / acts locally; // sends a literal slash.
• When the agent asks a multiple-choice question, the composer becomes a picker: ↑/↓ to move, space to toggle on multi-select, enter to confirm. Typing anything returns to the composer.
• Agent replies render as markdown.

Next

• Command reference — every command, flag, and key.
• Deploy a model — the manifest and the run/ + data/ contract.