Documentation / Guides
Using the CLI
Every `seshat` command, the options you will use most, background runs, sessions and the terminal shortcuts.
seshat with no arguments opens the interactive terminal interface, the same as seshat chat. Everything else is a subcommand.
Commands at a glance
| Command | What it does |
|---|---|
seshat chat | Interactive session in the terminal interface |
seshat run "prompt" | One task, then exit. Add --bg to run it in the background |
seshat config | Set the provider, model and keys, or show them with --print |
seshat sessions | List, inspect, delete and prune saved sessions |
seshat memory | Read and write the notes the agent keeps |
seshat trust | Trust the configuration files of a project |
seshat login | Sign in with a ChatGPT subscription (no API key) |
seshat doctor | Check configuration, storage, credentials and helper tools |
seshat repomap | Print a compact structural map of the repository |
seshat workflow run <file> | Run a workflow described in YAML or JSON |
seshat companion | Configure the companion profile added to sessions |
seshat ps, logs, attach, kill | Manage background runs |
seshat version | Print the version |
Chat
seshat chat # new session
seshat chat --continue # resume the most recent session
seshat chat --resume <session-id> # resume a specific one
seshat chat --model anthropic:claude-sonnet-5-5
seshat chat --permission-mode onRequest
seshat chat --no-tui # plain text mode, no full-screen interface
Useful options: --cwd DIR to work in another folder, --db PATH to use another session database, --show-thinking to display the model’s reasoning.
One-shot and background runs
seshat run "summarise the open TODOs in this repository"
seshat run --bg --name nightly-audit "review the last 20 commits for risky changes"
A background run is a local child process. Follow it with the other commands:
seshat ps # list background sessions
seshat logs nightly-audit -f # follow the output (--stream stdout|stderr)
seshat kill nightly-audit # stop it
Sessions
Sessions are stored in a local SQLite database.
seshat sessions list --status active --n 20
seshat sessions info <id>
seshat sessions delete <id...> # or --all
seshat sessions prune --older-than 30 --closed
Permission modes
--permission-mode decides who approves the actions of the agent:
| Mode | Behaviour |
|---|---|
onRequest | The default. Seshat asks before actions that need approval |
acceptEdits | Safe file operations in the working directory are allowed without asking |
auto | A classifier decides each action. With no classifier configured, Seshat asks you, and in a headless run it refuses |
never | Nothing is ever asked: a refused action goes back to the model as a failure. For headless and background runs |
granular | Fine-grained control of each approval flow |
bypass | No questions. Deny and ask rules, and the safety check, still apply |
Providers and models in the interface
Open the providers with ctrl+p, then Providers, then LLM. The list starts with the providers built into Seshat, the ones you have configured marked as such. The last entry, “More providers…”, opens the rest of the models.dev catalog, about 190 providers, with the ones you have configured first. Most of them have not been tried yet, so expect to meet a few rough edges, and tell us about them: the maintainers cannot test every provider, and reports and fixes from the community are how this list gets reliable. You do not have to open that list to find one: type in the search box and every provider is searched, the main ones and the others.
Choosing a provider asks for what it needs. Most take an API key. Codex is a ChatGPT account and has no key: the dialog shows an address and a code, opens your browser by itself, and waits while you enter the code there. The token is kept with its refresh token, and the next start renews it if it has expired. GitHub Copilot signs in with a code in the same way.
The model picker (ctrl+l) lists the models of the providers you have configured, so the list stays short. Until a provider is configured it offers the main providers, so you can set one up.
Shortcuts in the terminal interface
| Shortcut | Action |
|---|---|
ctrl+p | Settings and the list of shortcuts |
\ at the start of the prompt | The palette commands, listed over the prompt: type a few letters to filter, Enter to run. The last entry, “All Commands…”, opens the full dialog |
/ | The skills, listed over the prompt (after a space, or at the start) |
@ | Files and MCP resources to attach (after a space, or at the start) |
ctrl+m or ctrl+l | Models of the providers you have configured (on terminals that cannot tell ctrl+m from Enter, use ctrl+l) |
ctrl+, | Providers: the main ones, then “More providers…” for the rest of the catalog |
ctrl+s | Sessions |
ctrl+n | New session |
ctrl+t | Show or hide tasks |
ctrl+d | Show or hide details |
ctrl+y | Toggle yolo mode |
shift+tab | Enter or leave plan mode |
ctrl+j | New line in the prompt |
ctrl+o | Open your editor |
ctrl+f, ctrl+v | Attach a file, paste an image |
ctrl+u | Copy the last message |
ctrl+g | More help |
ctrl+c | Quit |
Running shell commands from the prompt
A line that starts with ! is a shell command, not a message to the agent. Nothing is sent to the model when you press Enter.
| You type | What happens |
|---|---|
!pip install rich | The command runs in the project folder and its output appears in a command panel next to the chat (at the right on a wide screen, under the chat on a narrower one). Scroll it with the mouse wheel. The output is not part of the conversation: it is not stored in the transcript, compacted, read by memory, or paid for in tokens. |
!!cat error.log | The same, and the output is also given to the agent: it is placed in front of your next message (cut to its start and end when long), so you do not copy errors by hand. |
:!sudo su | The terminal interface steps aside and gives the real terminal to the command until it ends, then comes back. Use it for anything that asks for input: a password, ssh, a shell, an editor. |
To give the agent an output you ran with a single !, open the command palette (\ at the start of the prompt) and choose Command Panel: Share Output With the Agent. The same palette has entries to show or hide the panel, to move between the last 20 commands and to clear it.
A ! command has no keyboard input, stops after 5 minutes and keeps the first megabyte of its output. It starts fresh each time, so a cd does not carry over to the next command. A password you type after :! goes straight to the command: the terminal interface never sees it.
Check your setup
seshat doctor # add --json for machine-readable output
It checks the local configuration, the storage, provider credentials and the helper tools, so it is the first thing to run when something does not work.
Updated on 2026-10-13