From b350e4dee2412e450b3844061f5c1bc2ec995923 Mon Sep 17 00:00:00 2001 From: t Date: Mon, 6 Jul 2026 15:00:37 -0600 Subject: catch up with latest panto cli developments --- cli.html | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'cli.html') diff --git a/cli.html b/cli.html index 0b14e57..80780f6 100644 --- a/cli.html +++ b/cli.html @@ -20,13 +20,10 @@
Source
- +
-

Reference

Command line

panto dispatches on its first argument. A handful of subcommands (lua, bootstrap, sessions, models, auth, help) short out before the agent loop; anything else — or nothing — starts the agent in the current directory.

CommandDoes
pantoStart a new conversation in the current directory.
panto --resume [<id>]Resume the most recent session, or one by id prefix.
panto sessionsList saved sessions for this directory.
panto models syncFetch models.dev and rebuild the base models.toml.
panto auth …Inspect and manage auth sessions (status / login / logout).
panto bootstrap [--force]Run the luarocks bootstrap and exit.
panto lua [args…]Drop into the embedded Lua interpreter.
panto helpPrint the usage summary (also --help, -h).

Starting a session

pantoStart a new conversation in the current directory.
panto --resume [<id>]Resume a previous session.

With no flag, panto opens a fresh session. --resume on its own reattaches the most recent session in this directory; --resume <id> resumes the session whose id begins with <id>. Unknown arguments are tolerated (and ignored with a warning), so passing flags panto doesn’t recognise won’t stop it from starting.

Needs a terminal

The UI runs in raw mode and requires an interactive tty on stdin/stdout. Piping input or redirecting output will refuse with an error rather than half-start.

panto sessions

panto sessionsList saved sessions for the current directory.

Sessions are grouped per working directory. Each line is the short id (the first eight hex characters of the session’s UUIDv7), the creation time trimmed to the minute, and the message count:

panto · sessions
$ panto sessions
7f3a9c2b 2026-06-12 09:41 24 messages
b81e0d44 2026-06-11 17:03 6 messages
a0c7f190 2026-06-10 22:18 41 messages

When a directory has no sessions yet, panto prints no sessions for <cwd>. Use any unambiguous id prefix from this list with panto --resume.

panto models

panto models syncFetch models.dev and rebuild the base models.toml.

sync is the only action. It fetches the models.dev catalog, walks the providers in your merged [providers] config, and for each one cross-checks the catalog against the models that provider actually serves — then writes the result to the base-layer models.toml ($PANTO_HOME/models.toml, else $XDG_DATA_HOME/panto/models.toml). Aliases, wire names, context windows, token caps, and pricing come along for the ride. A provider maps onto a catalog entry via model_catalog_name (falling back to the provider name); providers with no matching entry — or no usable synced models — are skipped.

panto · models sync
$ panto models sync
synced 42 model(s) across 3 provider(s) to ~/.local/share/panto/models.toml

Because it writes the base layer, your own user/project models.toml entries always layer on top and win. Re-run it whenever you want to refresh the catalog after providers ship new models.

panto auth

Manage the credentials behind your providers. With no action, panto auth defaults to status.

panto auth status
List every configured auth session and its state. api_key sessions read resolved or unresolved (key/env missing); oauth_device sessions show whether you’re logged in and roughly when the access token expires.
panto auth login <name>
Run the OAuth device flow for the named session. panto prints a verification URL and a user code, then stores (and, if configured, exchanges) the token. An api_key session has nothing to log in to.
panto auth logout <name>
Forget the stored token set for the named session.
panto · auth status
$ panto auth status
anthropic_api api_key resolved
openai_api api_key unresolved (key/env missing)
github_copilot oauth_device logged in (access expires in ~58m)

Auth sessions themselves are declared in config under [auth.<name>]. The provider that uses a session names it with auth = "<name>".

panto bootstrap

panto bootstrap [--force]Run the luarocks bootstrap, then exit.

The bootstrap pipeline prepares the embedded Lua runtime: it stages headers and the base agent tree, materialises the default config, and installs panto’s pinned batteries under $PANTO_HOME. The agent runs the very same pipeline on startup, so you rarely need this by hand — it’s here for first-run setup on a clean machine and for scripted / CI installs. Repeat runs no-op quickly.

--force
Wipe the per-Lua-version rocks tree ($PANTO_HOME/rocks/lua-X.Y.Z/) before reinstalling everything from scratch.

panto lua

panto lua [args…]Drop into the embedded Lua interpreter.

This is panto’s bundled Lua standalone (the same lua.c the agent embeds), with the luarocks runtime already bootstrapped — so require("luarocks.*") and any rocks installed under $PANTO_HOME resolve exactly as they do inside a session. Arguments after lua are passed straight through to the interpreter. Use it to experiment, or to drive luarocks to install extra rocks for your extensions:

shellbash
# run a script with panto’s Lua + rocks tree
-panto lua my-script.lua
-
-# install an extra rock into panto’s tree via the embedded luarocks
-panto lua -e 'arg[0]="luarocks"; require("luarocks.cmd").run_command("install","lpeg")'

Slash commands

Inside a session, any line that begins with / is a slash command rather than a prompt — it is handled locally and never sent to the model. The first word (after the slash) is the command name; the trimmed remainder is passed as its arguments.

/compactbuiltin
Compact the conversation now — summarise older turns to reclaim context while keeping a verbatim recent tail. (Compaction also runs automatically; see [compaction].)

/compact is the only built-in. Every other slash command comes from a Lua extension via panto.ext.register_command — see Lua extensions → register_command. An unrecognised command reports an error instead of reaching the model.

Environment

panto reads a few environment variables — for credentials and for locating its files. Configuration values can also pull from the environment via ${env:VAR} substitution (see Configuration).

VariableEffect
ANTHROPIC_API_KEYConsumed by the default Anthropic provider.
OPENAI_API_KEYConsumed by the default OpenAI provider.
PANTO_HOMEOverride the runtime / rocks-tree location. Also where the base config.toml and agent tree are staged.
PANTO_SESSION_DIROverride the base sessions directory. Defaults to $XDG_DATA_HOME/panto/sessions (or ~/.local/share/panto/sessions).
XDG_CONFIG_HOMELocates the user config: $XDG_CONFIG_HOME/panto/ (else ~/.config/panto/).
XDG_DATA_HOMELocates the base config + data: $XDG_DATA_HOME/panto/ (else ~/.local/share/panto/).
+

Reference

Command line

panto dispatches on its first argument. Some names are true subcommands (sessions, models, auth, bootstrap, update, lua, help); the flag forms start the agent itself, either interactively or in one-shot print mode.

CommandDoes
pantoStart a new interactive conversation in the current directory.
panto --resume [<id>]Resume the most recent session, or a specific session by id prefix.
panto -cAlias for bare --resume.
panto -p [prompt]Run one non-interactive turn, print assistant text, exit 0/1.
panto sessionsList saved sessions for this directory.
panto models syncFetch models.dev and rebuild the base models.toml.
panto auth …Show auth status, log in, or log out.
panto bootstrap [--force]Prepare the bundled Lua / luarocks runtime and exit.
panto updateInstall or refresh every rock listed in extensions.rocks.
panto lua [args…]Run the embedded Lua interpreter.
panto --versionPrint the panto version.

Starting a session

pantoStart a fresh interactive conversation.
panto --resume [<id>]Resume the latest or a specific saved session.
panto -p, --print [<prompt>]Run one turn without the TUI.

Interactive mode requires a tty on stdin and stdout. Print mode does not: the prompt can come from the flag argument or from piped stdin, and the command prints only the assistant text before exiting.

-c, --continue
Alias for bare --resume.
-m, --model <provider:alias>
Override the model for this run. A bare alias also works when it is unique across providers.
--effort <level>
Override the reasoning level for this run. This beats both models.toml knobs and [defaults] reasoning.
--no-extensions
Skip the Lua runtime entirely. The core still starts, but because the shipped tools are extensions the agent runs with no tools.

Unknown arguments are errors now

Agent-mode flag parsing is strict. An unrecognized argument prints an error and exits instead of being ignored.

panto sessions

panto sessionsList sessions for the current directory.

Sessions are stored per working directory. The listing is newest-modified first and prints the shortest unambiguous id prefix, the modified timestamp, message count, model, and last user message:

panto · sessions
$ panto sessions
ID MODIFIED MSGS MODEL LAST MESSAGE
0197c2a4 2026-07-01 14:32 18 sonnet add json mode to stats
0197bfe1 2026-06-30 09:11 6 gpt-5 clean up the parser errors
~/.local/share/panto/sessions/--Users-travis-Code-ledger--

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

panto models

panto models syncFetch models.dev and rebuild the base models.toml.

The sync command looks at the providers that resolved from your layered config, maps each one to a models.dev catalog entry, optionally intersects that with the provider's own live /models listing, and writes the result to the base-layer models.toml at $XDG_DATA_HOME/panto/models.toml (or ~/.local/share/panto/models.toml).

panto · models sync
$ panto models sync
synced 42 model(s) across 3 provider(s) to ~/.local/share/panto/models.toml

Your user and project models.toml layers still sit on top and win.

panto auth

With no action, panto auth defaults to status.

panto auth status
Show every configured auth session. API-key sessions report resolved or unresolved (key/env missing); OAuth sessions report whether they are logged in and when the current access token expires.
panto auth login <name>
Run the OAuth device flow for the named session and persist the resulting token set.
panto auth logout <name>
Delete the stored token set for the named session.

panto bootstrap

panto bootstrap [--force]Run the runtime bootstrap pipeline, then exit.

Bootstrap stages the base agent tree, creates the generated base config as needed, and prepares the versioned luarocks tree under the data home. The normal agent startup path runs the same bootstrap automatically.

panto updateInstall or refresh the rocks listed in extensions.rocks.

panto update is the explicit “go hit luarocks again” command. Startup only installs missing rocks; changing a version pin or forcing a re-resolve is what update is for.

panto lua

panto lua [args…]Run the embedded Lua interpreter with panto's runtime wired in.

This is the same embedded Lua build panto uses internally, with package paths and luarocks configured the same way a session sees them. It is handy both for experiments and for driving luarocks manually:

shellbash
panto lua my-script.lua
+panto lua -e 'arg[0]="luarocks"; require("luarocks.cmd").run_command("install","lpeg")'

Slash commands

Lines beginning with / are handled locally inside the TUI and never sent to the model.

Built in
/help, /quit, /model, /reasoning, /new, /resume, /status, and /compact.
Extension-defined
Lua extensions can register more slash commands with panto.ext.register_command.

Environment

VariableEffect
ANTHROPIC_API_KEYConsumed by the default Anthropic provider.
OPENAI_API_KEYConsumed by the default OpenAI provider.
PANTO_DEBUGWhen non-zero, route std.log output to <data home>/debug/<session>.log instead of the terminal.
PANTO_SESSION_DIROverride the base sessions directory. panto still appends one encoded subdirectory per working directory.
XDG_CONFIG_HOMELocates the user config and user extensions directories.
XDG_DATA_HOMELocates the data home: base config, base models, sessions, auth cache, agent tree, and rocks.
-- cgit v1.3