Command reference

Run aura <command> [subcommand] --help for the full option list at any point; aura <noun> on its own lists that noun’s verbs.

Commands

Command	What it does
aura deploy [name]	Upload the deployment defined in [tool.aura.deployment.<name>] (--config <path>, --dry-run, --verbose)
aura chat --project <id>	Chat with a project (--conversation <id>, --new-conversation, --title <text>, --message <text>)
aura init	Add a [tool.aura.deployment.<name>] section to pyproject.toml (--config <path>)
aura deployment list	List your company’s deployments
aura deployment check [handle|name]	Run the server-side runnability check (--config <path>)
aura deployment delete <handle|name>	Delete a deployment and every file in it (y/N prompt; --yes to skip)
aura project create <handle> --name <name>	Create a project from a deployment (--description <text>)
aura project list	List your projects
aura project checkout <id> <ref>	Reset a project’s workspace to a snapshot, tag, or deployment — discards uncommitted workspace state (y/N prompt; --yes to skip)
aura project delete <id>	Delete a project and everything in it (y/N prompt; --yes to skip)
aura conversation list --project <id>	List a project’s conversations
aura conversation delete <id> --project <id>	Delete one conversation (y/N prompt; --yes to skip)
aura snapshot list --project <id>	List a project’s snapshots as a lineage tree (--flat for newest-first)
aura snapshot list-files <ref> --project <id>	List the files captured in one snapshot
aura snapshot read <ref> <path> --project <id>	Print one file from a snapshot to stdout
aura snapshot tag list --project <id>	List the project’s tags and what they point at
aura snapshot tag set <name> <snapshot-id> --project <id>	Point a tag at a snapshot, creating or moving it
aura config	Show every setting, its value and its source
aura config set <key> <value>	Write base_url, theme or full_dates to the config file
aura config unset <key>	Remove a setting, falling back to the environment or the default
aura config path	Print the config file’s location
aura completion [shell]	Print the shell completion script — bash, zsh or fish, detected from $SHELL when omitted (see Install)

Every command takes --base-url / --api-key (or AURA_BASE_URL / AURA_API_KEY) except aura init, aura config and aura completion, which are offline. Values resolve flag → environment → config file → default; see Configure. Commands that print timestamps also take --full-dates, which shows the exact stamp instead of 3h ago.

aura deploy reports one summary line per run rather than a line per file; --verbose restores the per-file log, and --dry-run lists the resolved files without uploading.

Reading a run’s results

Every completed solve freezes an immutable snapshot, so aura snapshot reads a given run’s own copy rather than a live workspace a later run may have overwritten.

<ref> is a snapshot id or a tag name, so a pipeline can ask for best-known without tracking ids.

aura snapshot list --project <id>                      # the lineage tree
aura snapshot list-files best-known --project <id>     # what that run captured
aura snapshot read best-known solution --project <id> > solution.json

read prints bytes to stdout unchanged — nothing reformats or pretty-prints, so a redirect is byte-faithful. The path solution is an alias for whatever path the solver recorded for that run; a real file named solution wins over the alias. A solution is JSON by convention only, so at a terminal read refuses binary content rather than garbling it — redirect or pipe instead.

Labels name a run; tags are movable pointers

A snapshot’s label describes the run that produced it and does not change. A tag is a name you move between snapshots — point best-known at a better run and everything downstream follows. Labelled, tagged, manual, and current snapshots are retained; the rest age out.

Deleting a deployment cannot be undone

aura deployment delete purges every file under the deployment and frees its name — a new deployment claiming that name starts empty. Projects already created from it keep their own copy and are unaffected; the command reports how many there were.

The deployment manifest

aura deploy reads a [tool.aura.deployment.<name>] table, normally in the model folder’s own pyproject.toml — the file that lands as run/pyproject.toml. Build backends ignore unknown tool tables, so the manifest travels with the artifact without affecting it.

pyproject.toml

[tool.aura.deployment.vrp]
model_folder = "."               # uploaded under run/   (default ".")
data_folder  = "../define/data"  # uploaded under data/  (required)
include      = ["pyproject.toml", "run.py", "README.md", "src/solver/**"]
data_include = ["**"]
exclude      = ["personal_infos.txt", "notes/**"]

Key	Default	Means
model_folder	"."	Uploaded under run/
data_folder	required	Uploaded under data/
include	["**"]	Globs relative to model_folder
data_include	["**"]	Globs relative to data_folder
exclude	—	Applies to both folders; wins over include

• The deployment name is the table key: lowercase letters, digits, hyphens. Several deployments may live in one pyproject.toml; aura deploy <name> picks one, and the name is optional when only one is defined.
• Folder paths resolve relative to the pyproject.toml. aura deploy searches upward from the current directory for one carrying a [tool.aura] table, or takes --config <path>.
• Built-in excludes always apply: dot-prefixed files and directories (.git, .venv, .env, …), __pycache__, node_modules, dist, venv, *.pyc. The server additionally rejects dot-prefixed and executable paths.
• Deploying is a sync: after the uploads, remote files no longer present locally are removed, so renames and deletions leave nothing stale.

aura deploy --dry-run     # print exactly what would upload, change nothing

Chat TUI keys

Key	Does
enter	Send
shift+enter	Newline — compose a multi-line message
← →, alt+← alt+→	Move by character, by word (esc b / esc f also work)
home end, ctrl-a ctrl-e	Start / end of line
ctrl-w or alt+backspace	Delete previous word
ctrl-u, ctrl-k	Delete to line start, to line end
ctrl-d	Delete forward (backspace always deletes back)
↑ ↓	Recall history; within a multi-line message, move between its lines. While the command menu is open, move through it
tab	Fill in the highlighted command, while the command menu is open
pgup pgdn, mouse wheel	Scroll the transcript; scrolling back to the bottom re-sticks
esc	Dismiss the command menu; otherwise cancel the running turn and stay in the session
ctrl-c twice, or exit	Quit when idle — the first ctrl-c abandons the line and arms the quit

shift+enter needs a capable terminal

A plain terminal sends the same bytes for shift+enter as for enter, so the TUI enables the kitty keyboard protocol to tell them apart. Terminals that implement it — kitty, Ghostty, WezTerm, foot, recent Windows Terminal — get shift+enter; everything else falls back to alt+enter.

Pasted text is inserted literally, newlines included, so a multi-line paste does not send on its first line break.

In-session commands

Inside aura chat, a leading / means “act locally” — anything else is a turn for the agent. // escapes to a literal slash, so a path can still be sent as a message.

Command	Does
/help	List the commands available in this session
/checkout	List available checkout targets (tags, snapshots, deployments); /checkout <ref> resets the workspace to one (y/N prompt in-session)
/exit	Leave the chat session

Typing / opens a menu of them above the composer, so there is nothing to memorise: keep typing to narrow it, ↑/↓ to move, tab to fill the name in, enter to run the highlighted one, esc to dismiss. A near-miss still matches, so a typo shows the command you meant rather than an empty list. The menu closes once the name is settled and its arguments have started.

/checkout discards uncommitted workspace state

The server records the checkout on the session’s conversation, and the agent is told on its next turn that the workspace changed under it, so you can keep iterating in the same thread. The same reset is available outside chat as aura project checkout <id> <ref>.

Quick replies

When the agent asks a multiple-choice question it stops and waits, and the composer is replaced by a picker:

Key	Does
↑ ↓	Move between options
space	Toggle, on a multi-select question
enter	Confirm
esc, or typing anything	Leave the picker for the composer

Every question ends with a type your own answer row, and cards with several questions are walked one at a time. If the picker has been dismissed, typing numbers still works: the transcript numbers options continuously across the card, so 2 or 1,3 answers directly.

Rendering

Agent replies render as markdown: tables become grids, fenced code is syntax-highlighted, links resolve to their text plus a readable URL.

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 read as 3h ago unless --full-dates is passed.

Colour degrades by capability — 24-bit where COLORTERM reports truecolor, the nearest xterm-256 index on a -256color terminal, the basic sixteen otherwise. NO_COLOR and non-TTY output stay plain; FORCE_COLOR overrides the detection.

Below 24×6 the frame is replaced by a size hint.

Exit codes

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