CLI Usage

Seshat CLI app is the fastest way to use the agent runtime today. It is built for developers, vibecoders, open-source contributors, and technical users who want an AI coding agent in the terminal, whether they are pushing Seshat forward, working inside their own repository, or running local models and cheaper LLM providers without losing the serious tooling surface.

Why this CLI exists

The CLI is both a real product and a proving ground. It lets us validate agent workflows, tool UX, provider setup, MCP integration, skills, permissions, and session design before features become part of the official desktop experience. It is the shortest feedback loop between the runtime engine and real users.

Who the CLI is for

This CLI app is not a toy shell wrapper around a prompt. It is a terminal-first agent workspace for people who want a coding assistant, an autonomous coding tool, a repo-aware AI terminal, or a practical way to work with LLMs through a TUI instead of a browser chat. If you care about speed, scripting, keyboard flow, local inference, lower model cost, or testing agentic features before they land elsewhere, this is the right surface.

Developers

Use Seshat in real codebases, inspect files, run commands, switch models, and pressure-test the runtime against production-like work.

Vibecoders

Stay in flow with a terminal agent that can reason over a repo, apply structure, and work with cheaper providers instead of premium-only defaults.

Open-source contributors

Use the same CLI surface we use internally to discover rough edges, test features early, and help shape what becomes stable in the engine and desktop app.

Local-first users

Run Ollama or other compatible providers, plug in lower-cost APIs, and keep a strong tool surface even when optimizing for price or privacy.

One runtime, two working modes

Use seshat chat when you want the full TUI and a long-running agent session. Use seshat run when you want one prompt, one answer, and no interactive shell.

The commands that matter first

You do not need the entire command surface on day one. These are the commands that define the real CLI workflow right now: starting a chat, running a one-shot task, checking config, managing sessions, and validating optional tooling.

CLI

seshat chat
seshat run "Summarise this repo and suggest the next useful change"
seshat config --print
seshat sessions list
seshat setup --check

Chat

seshat chat opens the interactive TUI and is the default entry point for most users.

Run

seshat run is the fast path for scripting, tests, and quick repo-level prompts.

Config

seshat config selects providers, models, credentials, and search-provider keys.

Sessions

seshat sessions lists, resumes, deletes, and prunes saved conversations.

Start with the interactive TUI

The CLI app opens directly into the terminal UI, where Seshat streams answers, runs tools, keeps session history, and exposes the settings hub without leaving the session. This is where the runtime is easiest to understand, because prompts, tool calls, attachments, approvals, thinking traces, and session state all stay visible.

Seshat CLI home screen — The home screen is the clean starting point before the first active session.

Seshat CLI running inside an active session — Once a session is live, the CLI becomes the operator console for prompts, tools, attachments, and approvals.

Settings, providers, and models

The TUI already exposes the most important configuration flows. ctrl+p opens Settings,ctrl+, jumps to providers, and ctrl+lopens the model picker. That makes the CLI app usable for simple users, repo-first vibecoders, and developers without forcing everyone through raw JSON on the first day. It also makes it practical to move between premium APIs, OpenAI-compatible endpoints, self-hosted services, and local models as your constraints change.

Seshat settings overview — Settings already centralize commands, providers, models, tools, MCP, and skills.

Seshat model picker — Large-task and small-task models can be switched directly from the CLI.

Seshat provider categories — Providers are split by capability, including LLM, image, speech, and web search.

Seshat LLM provider configuration — Provider setup can be driven from the TUI instead of forcing manual config edits up front.

Day-one keybindings

These shortcuts are the practical minimum worth memorizing. They cover navigation, settings, sessions, and the compose box features you will use constantly in a real project.

ctrl+p opens the Settings hub, including Tools, MCP, and Skills.
ctrl+, jumps straight into provider management.
ctrl+l opens the model picker. Some terminals also support ctrl+m.
ctrl+s opens the session switcher, where sessions can also be renamed or deleted.
ctrl+n starts a new session without leaving the TUI.
ctrl+g opens the extended help surface.
Inside the composer, use @ to mention files, \ to open commands, ctrl+o for the editor, and ctrl+f to add an image or attachment.

Sessions are a first-class workflow

Seshat does not treat a chat as disposable terminal output. Sessions are stored, can be resumed from the CLI, and have their own artifact directories for screenshots, downloads, plans, pasted content, and generated files. That matters for long-running agent work, iterative coding sessions, and open-source feedback loops.

Session Commands

seshat chat --continue
seshat chat --resume <session-id>
seshat sessions list
seshat sessions info <session-id>
seshat sessions prune --older-than 30

Where config and runtime files live

There are two layers to keep in mind. The CLI keeps global runtime state under its own runtime root, and each project keeps local state in a dedicated data directory. By default, the CLI runtime root is ~/.config/seshat-cli, and the project data directory is .seshat at the repository root or current working directory.

Paths

~/.config/seshat-cli/
~/.config/seshat-cli/seshat.json
<project>/.seshat/
<project>/.seshat/seshat.json

SESHAT_RUNTIME_ROOT overrides the global runtime root when you need a custom location.
The global config file is seshat.json under the runtime root.
The workspace config file is .seshat/seshat.json unless options.data_directory points elsewhere.
Session artifacts, logs, pasted files, plans, and tool downloads are stored under the runtime root on a per-session basis.

MCP, web search, and skills

The CLI is already opinionated here. Settings exposes an MCP view for server status and reconnect or disable actions, a Skills view for discovered skills, and provider sub-pages for web-search configuration. Under the hood, these map to themcp, options.skills_paths, andoptions.disabled_skills fields in config. This is where the runtime starts to feel like an extensible agent platform rather than a simple terminal chatbot.

Seshat web search provider configuration — Web search providers can be configured from the same provider system as the main LLM setup.

Seshat commands panel — The command surface becomes more valuable once custom commands and MCP prompts are added.

Config Shape

{
  "mcp": {
    "docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  },
  "options": {
    "skills_paths": ["~/.config/seshat-cli/skills", "./skills"],
    "disabled_skills": ["legacy-skill"]
  }
}

A surface that evolves with the runtime

The CLI app is intentionally close to the engine. As the agent runtime grows, the CLI will keep exposing new tools, new workflows, better provider routing, richer MCP support, stronger skill discovery, and more stable automation paths. Its direction will not come only from internal roadmap decisions. It will also move with the open-source community, because this is the place where advanced users can test features early and make the product sharper before those capabilities are frozen into more official surfaces.

What to read next

This page gives the operating map of the CLI. Next, we can split it into focused guides for provider setup, local models, cheap model stacks, MCP servers, skills, and configuration files once the rest of the docs surface is ready.

Configuration First Agent