Chat session

aura chat opens a full-screen session: 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.

Options

Option	Does
--project <id>	The project to chat with. Defaults to the selected one
--conversation <id>	Target a specific conversation
--new-conversation	Start a fresh conversation in the project
--title <text>	Title for the conversation --new-conversation creates
--message <text>	Take one turn and exit, printing the reply plainly — no full-screen UI
--timeout <seconds>	How long to wait for a turn before giving up (default 900)

Without --conversation or --new-conversation the session picks up the project’s active conversation, replaying its history first.

A solve can outlast the default wait

--timeout bounds how long the CLI waits, not how long the turn may run. The turn keeps going server-side either way, so a timed-out solve is still working and its reply still lands in the conversation — raise --timeout rather than re-sending the message, which would start a second turn.

Ctrl-C during --message stops the turn, not just the CLI

Interrupting a one-shot turn cancels it server-side before exiting 130. Otherwise the turn would keep running, and billing, after you left.

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
ctrl-o	Open the workspace file browser
drag with the mouse	Select text — releasing copies it to the clipboard
click a ⧉ n badge	Copy that whole message; same as /copy n
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 abandons the line and arms the quit

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

Selecting text is the session's own, not your terminal's

Drag across the transcript and the covered text highlights; release and it goes to your clipboard, styling stripped — so a snapshot id pastes as an id. Any keystroke or scroll clears the highlight.

Only message text can be selected. The margin down the left — the speaker marks — along with the elapsed time, the copy badge and the scrollbar are part of the frame, not the conversation, so a drag stops at the text however far it reaches and you never paste decoration. Dragging is meant for grabbing a snippet; use /copy n or /copy for a whole message or the whole thread.

Settled messages also carry a ⧉ n badge at the right edge. Click it to copy that message whole — it ticks over to confirm — or type /copy n for the same thing without the mouse. The numbers run from the start of the conversation, so they don’t shift as you scroll. /copy on its own takes the entire thread. A reply still streaming has no badge, since only part of it has arrived; it gets one as soon as the turn finishes.

This is done by the session rather than by the terminal, because it has to be: a terminal hands the mouse to the application or keeps it, never both, so an app that scrolls on the wheel has already taken every click and drag with it. Copying uses OSC 52; terminals that don’t implement it (and tmux without set-clipboard on) will highlight but not copy.

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.

Slash commands

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. Arguments are taken as a shell would take them, so a quoted or backslash-escaped argument holding spaces arrives as one: /checkout "june pilot".

Command	Does
/help	List the commands available in this session
/copy	Copy the whole conversation as plain text; /copy 7 copies message 7 alone
/checkout	List available checkout targets (tags, snapshots, deployments); /checkout <ref> resets the workspace to one (y/N prompt in-session)
/dashboard	Print this project’s run dashboard URL and open it in your browser (Dashboard)
/files [prefix]	Open the workspace file browser, on one subtree if given
/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>. Neither touches the project’s agent config — only checkout onto a deployment pulls that.

Quick replies

When the agent asks a multiple-choice question it stops and waits, and the composer becomes 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 a card with several questions is 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.

Workspace files

ctrl-o — or /files [prefix] — opens the project’s workspace over the transcript: the file tree on the left, the highlighted file’s contents on the right. The composer stays put underneath, because the reason to look at a file mid-conversation is usually to talk about it. Files can also be added and removed from here.

Key	Does
↑ ↓, pgup pgdn, wheel	Move through the tree
enter, →	Open a file; unfold a directory (→ then steps into it, enter folds it again)
←	Fold a directory, or step up to the one holding this file
any character	Filter — matches anywhere in a path, and the tree flattens to the files that match
tab	Put the highlighted path in the composer and close
ctrl-u	Upload a local file into the highlighted directory
ctrl-d	Delete the highlighted file, after a y/N
esc	Clear the filter, then close. From a file’s contents, back to the tree
ctrl-c	Close and arm the quit, as it does anywhere else

Files load as you move: a highlight that settles for a moment fetches that file. One over 128 KB — or of a type there is nothing to show as text — waits for enter instead, so moving through a directory of solver output doesn’t pull megabytes down a row at a time.

Markdown renders as markdown, which is what define/pdd.md — the problem definition — is. Everything else is shown with line numbers, clipped rather than wrapped. Once a file’s contents have the keyboard — after enter or → — ↑/↓ scroll a line and pgup/pgdn a page; the focused pane is the one whose title is bold. Below 60 columns there is one pane instead of two, showing whichever side has the keys.

The browser opens only between turns, and shows the same four directories aura workspace file list does.

Uploading from the session

ctrl-u turns the right-hand pane into a browser for your own machine, so a file is picked rather than typed. The workspace keeps the left-hand pane and its highlight becomes the destination, which is why nothing asks you where the file should go:

 workspace       → data/fleet/ │ local /Users/dennis/Downloads      4 items
  ▾ data/                      │   ..
 ❯  ▸ fleet/                   │   invoices/
      orders-june.csv   1.2 MB │ ❯ orders-july.csv                 890.0 KB
  ▾ define/                    │   photo.png                         2.1 MB
 › orders-jul                                     → workspace data/fleet/

The two file systems are labelled and spelled differently on purpose: local paths are absolute and workspace paths are relative to the project’s tree. The bottom line names the destination in full, so the remote side stays visible on a narrow terminal, where only one pane fits.

Key	Does
↑ ↓	Move through the directory
enter	Send the highlighted file; on a folder, or on .., open it
→, ←	Open the highlighted folder; go up one
any character	Filter this directory — or, once it holds a /, a path to go to
esc	Clear what you typed, then leave the local pane

A path with spaces works typed or dropped: quoting and backslash escapes are honoured, which is what a terminal pastes when you drop a file onto it. A dropped path is navigated to — the folder opens with the file highlighted — so enter on a file is the only thing that ever writes.

The file keeps its own name, so sending one into a directory that already holds that name replaces it — and because that cannot be undone, it asks first, on the same row and in the same words a delete does. Only regular files can be sent, up to 128 MB.

Nothing on your machine is changed, and nothing there can be deleted from here.

Deleting a file

ctrl-d removes the highlighted workspace file, after a y/N on the same line; any other key cancels — as it does for the overwrite above, so the one unrecoverable answer is never the default. Directories are refused rather than emptied — the files API’s delete is not recursive, so delete the files inside instead. aura workspace file delete <path> is the same removal from outside a session.

Writing from chat always tells the agent

An upload or a delete made here announces itself on the session’s conversation, so the agent re-reads the file — or stops relying on it — on its next turn rather than answering from what it read earlier. Outside a session that is opt-in: aura workspace file upload and ... delete announce only with --conversation <id>, because a scripted job has no thread to post into.

Rendering

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

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.