Command line & the prompt

Command line#

Invocation	Meaning
shuvarie [WORK_DIR]	Start a new session (optionally in another directory — the session database lives there too)
-c, --current	Resume the most recently updated session
-s, --session <UUID>	Resume a specific session by UUID
--config <FILE>	Use an explicit config file, bypassing the workspace-config trust scan
shuvarie run <PROMPT>	Run one prompt headlessly, without the TUI (see below)
shuvarie import <FILE>	Import a session JSON snapshot and exit
shuvarie export [DEST]	Export a session to JSON and exit (-s picks the session, default the most recent; an empty DEST picks an automatic path)
shuvarie update	Update the binary to the latest release
-h, --help	Show help
-V, --version	Show version

When you quit, Shuvarie prints the exact command to reopen the session:

This session can be reopened with:

  shuvarie -s <session-uuid>

Headless mode#

shuvarie run <PROMPT> drives the agent with a single prompt and no TUI: it is the same core, config and permission engine, with the terminal left alone. The prompt is every word after run, joined with spaces.

shuvarie run fix the failing tests in src/parser
shuvarie -c run --permission-handle allow-all now commit it   # resume a session

The assistant’s reply is streamed to stdout as it arrives, so it pipes into less, a file or another program cleanly. Everything else — tool activity, permission decisions, retries, warnings and the resume hint — goes to stderr. A run that finishes cleanly (or is cancelled) exits 0; a failed turn exits non-zero. -c/--session resume a session first, exactly as they do interactively.

Flag	Meaning
--permission-handle <MODE>	How ask gates are answered: allow-ask (default, allow the single call), deny-ask (deny it, cutting the turn) or allow-all (allow and remember the scope for the rest of the run)
-t, --transient	Use an in-memory session database, so the run leaves nothing behind (cannot be combined with -c/-s)
--trust <SPEC>	The workspace trust this run starts under: all, none, or a comma-separated list of categories (contexts,skills,configs). Without it the recorded decision for the workspace is used, else nothing

A headless run never prompts for workspace trust and never writes trusts.kdl: it takes --trust, or the decision already recorded for the directory. The question tool is not offered to the model in this mode, so it cannot block on a dialog; a stray ask is dismissed with a warning.

Updating#

shuvarie update fetches the latest GitHub release, verifies the download against the release’s SHA256SUMS and swaps the binary in place — picking the right build for your platform, including musl. When it finishes, restart shuvarie to use the new version.

The prompt#

• Enter submits, Shift+Enter inserts a newline.
• A leading ! runs the rest of the line as a local shell command instead of prompting the agent (bash mode).
• A leading / or : starts a slash command (list). Matching is case-insensitive; type the trigger twice (//) to send a literal slash. An autocomplete menu appears as you type.
• A submit that opens with / or : but matches no built-in, custom or skill command is held back as a likely typo, with the prompt “This might be an invalid slash command”: Enter sends it as plain text anyway, Esc hands it back to the composer to keep editing.
• /skill:<name> [args] expands a skill into its stored prompt and sends it.
• /attach [dir] fuzzy-finds a file and attaches it to the next prompt: documents are converted, images ride along as multimodal parts (see Attachments). What you picked shows above the input as a pending strip — attachments are structural, never text in the composer — and /manage-attachments adds, reorders and removes them. A file dragged onto the terminal arrives as an attachment too, and Ctrl+Shift+V (or Alt+Shift+V) pastes an image straight off the system clipboard.

Unstaged changes#

In a git worktree with work that is not staged, a submitted prompt is held and the worktree is reported first — the turn would otherwise run against uncommitted work:

Key	Action
s	Run git add --all, then send
c	Send anyway, leaving the worktree alone
Esc	Cancel: the draft goes back to the composer

Only the unstaged half of git status is listed (tracked files whose worktree copy changed or vanished, plus untracked paths), so work you already staged is not what the prompt is about. It never fires mid-turn — while the agent is busy a submit steers it instead — and a workspace that is not a git worktree has nothing to warn about.