Reference

Command line

panto dispatches named commands, while agent flags start an interactive session or, with -p, one-shot print mode. run is the agent-bundle form: panto run <file.agent> extracts the bundle and starts a session; other dispatcher subcommands run and exit. --resume <id> consumes a positional session-id prefix, so not all positional text is an error.

Configuration is merged in this order: state.toml at $XDG_DATA_HOME/panto/state.toml, then base, user, project, and local config.toml. State is the lowest-precedence remembered picker layer; delete it to reset picker selections. Git-ignore ./.panto/local/ when it contains machine-specific settings.

Starting a session

Interactive mode requires both stdin and stdout to be ttys: panto exits with an error when either is not a tty. If no matching session exists for an explicit id, or the prefix is ambiguous, panto exits with an error. Bare --resume and -c/--continue resume the most recent session; when none exists, panto starts a fresh one.

Print mode

An inline prompt wins. Without one, panto reads a non-TTY stdin stream to EOF; all-whitespace input is an error unless panto run <file.agent> supplies a non-whitespace PROMPT.md. A fresh bundle can use that file even with a TTY; --interactive skips it. Print mode streams only assistant text to stdout, flushes each text delta, and adds a newline when a text block ends without one. Bootstrap and rock-install progress goes to stderr.

The selected or newly created session is persisted like an interactive session. Turn failures go to stderr as error: turn failed: <ErrorName> and exit 1; success exits 0. OAuth resolution is noninteractive, so an unauthenticated provider fails instead of starting device login. Combine -p with --resume/-c, -m/--model, -e/--effort, -t/--theme, and --no-extensions.

panto sessions

Sessions are stored per working directory. The listing is newest-modified first and prints a disambiguating id prefix of at least eight characters, the modified timestamp, message count, model, and last user message. Newlines, tabs, and carriage returns in the last message are flattened, and the message is width-truncated. Set COLUMNS to control the table width; an absent or invalid value defaults to 120.

If there are no sessions yet, panto prints no sessions for <cwd> and then the directory it would use.

panto models

This is the only valid models action. It fetches models.dev, builds the base catalog from configured providers, and writes it to $XDG_DATA_HOME/panto/models.toml (or ~/.local/share/panto/models.toml). Recognized reasoning capabilities are included for applicable OpenAI-style models. A skipped-provider notice is printed when applicable.

The base catalog is merged with user, project, and local models.toml layers, including ./.panto/local/models.toml for local overrides. An omitted action prints usage: panto models sync; an unknown action or extra argument prints that diagnostic and returns success.

panto auth

With no action, panto auth defaults to status.

panto bootstrap

Ordinary bootstrap is intended to be fast and idempotent. --force wipes the per-Lua-version tree before bootstrapping it. Unknown bootstrap flags are errors. Successful completion reports the ready tree.

panto version

panto version prints the version; --version is an alias.

panto update [--check]

Without --check, panto checks, verifies, and installs the latest release. --check reports availability without installing. Invalid update arguments print usage: panto update [--check] and exit 2; release or permission failures are reported as startup failures.

panto extension

panto extension install

panto extension update

panto extension remove <name>

install rock:<spec> installs the LuaRocks spec and records it in state.toml. A git URL is cloned into the data-home dist/<name> and linked from the config-home extensions/<name>. update updates those git clones and all configured rocks. remove removes a managed git extension or a recorded rock. Missing arguments, an extra argument to the git form/update/remove, or an unknown action prints usage and exits 2; the rock: form consumes remaining words as the rock spec. Friendly failures such as an existing extension or missing init.lua exit 1.

panto lua

panto bootstraps the LuaRocks runtime, then passes every argument after lua to the standalone embedded Lua interpreter. The standalone state provides require("panto"), including panto.ext tools, commands, protocols, foreground processes, events, highlighting, styles, JSON helpers, session/model queries, model resolution, and the panto.text.* helpers. A nonzero Lua exit code becomes panto's process exit code.

panto lua my-script.lua
panto lua -e 'print(require("panto").text)'

Slash commands

Lines beginning with / are parsed locally inside the TUI and never sent to the model. Arguments are the trimmed remainder of the line. Unknown commands show [unknown command: <line>].

Lua extensions can register additional commands with panto.ext.register_command { name, description, handler }. The live registry supplies /help and completion; names must not collide with native or other Lua commands. A Lua handler may await asynchronous work: input pauses while it runs, then its returned string or formatted error is emitted.

Shell lines

In the interactive TUI, a line beginning immediately with ! runs a shell command with /bin/sh -c. !<command> stages the formatted command result as a user message for the next model prompt; it does not open a turn. !!<command> stages the same result and immediately opens a model turn. A bare ! displays [empty shell command]; a leading space makes it ordinary model text.

The child shell's stdin is ignored, and its stdout and stderr are merged. Shell output is tail-capped at 50 KiB for the conversation and the transcript preview at 2 KiB. ANSI and control sequences are stripped except newline and tab, and invalid UTF-8 is repaired. Esc or Ctrl+C cancels the command; it times out after five minutes, then receives TERM followed by KILL after 250 ms.

The generated base config seeds [api] timeout = 300 and retries = 3, [compaction] keep_verbatim = 20000, and [tui] tools_collapsed, with default OpenAI and Anthropic providers and auth. The data home includes agent/, auth/, and versioned rocks/lua-5.4.7/ trees. state.toml also persists extensions.rocks.

Environment