Skip to main content
Running seri with no task opens a full-screen terminal session. /login, /config, /permissions and /usage are session commands rather than shell verbs. The shell verbs are serve, exec, doctor and update. None of those four opens a billed session.

​
Flags

Flags work in any position. Remaining words are the first task. Everything after -- is treated as text rather than as flags, which is the documented escape when you need to pass something flag-shaped, including a task that looks like a verb.
On a real terminal that string is submitted as the first turn of the session. Without a terminal, the same invocation runs that one turn and exits. A task on the command line never enters plan mode. seri -- "plan this" is an ordinary turn. A positional /plan is prompt text.
--dangerously-skip-permissions turns off the approval prompt for the whole run. It is for attended, high-trust work. Cycling to auto with /mode inside the session is the same idea, with a keystroke to get back out of it. --permission-prompts none does not skip the gate. It denies a call that would have asked, and path deny, containment, and hooks still run.

​
While it starts

seri shows a splash while it loads the model catalog and prepares the session. You can start typing your first task there. What you type is queued and submitted once the session is ready, so a slow catalog fetch never costs you the thought you were mid-way through.

​
Exit codes

The line between 0 and 1 is whether the run accomplished anything, not whether anything was printed.
  • A turn that ends with no tool call exits 0, unless every write it attempted was declined and nothing ran, which exits 1.
  • A read-only block is not a failure. It still exits 0.
  • The turn budget running out, and repeated denials, both exit 1.
  • Cancelling with Ctrl-C ends the turn as aborted rather than as an error, and leaves the session resumable.
  • Quitting with /exit or Ctrl-D while a turn is in flight exits 1, because the turn did not finish.

​
Sessions

Every session is a file on disk. --continue opens the most recent one and --resume <id> opens a specific one, both with the conversation intact. They start a new turn only if that session is still waiting for a reply. A finished session comes back as it was. Type a new task, or pass one on the command line. /clear inside a session starts a new one rather than deleting the old one, so a session you cleared is still reachable with --resume.
The checkpoint store keeps the 20 most recently touched sessions per project. An old session’s conversation stays on disk indefinitely, but the checkpoint history behind its /undo and /rewind can be pruned once 20 newer sessions exist in the same project.

​
Profiles

--profile <name> swaps the whole profile root. Config, keys, sessions, checkpoints, memory, agents, skills, rules, MCP servers and hooks all come from ~/.seri/<name>/ instead of ~/.seri/, and a named profile never falls back to the default root. SERI_PROFILE sets the same thing, and the flag wins over it. /profile new <name> creates one from inside a session. See Profiles for what a profile is good for.

​
The local daemon

seri serve starts a loopback daemon for this profile and prints the endpoint it is listening on. It stays in the foreground until Ctrl-C or SIGTERM, then stops the server and removes its descriptor. seri exec <task> sends one task to that daemon. If no daemon is running for this profile it exits 1 and tells you to start one with seri serve. -- before serve, exec, doctor or update is the escape that makes those words a task instead of a verb.

​
Doctor

seri doctor prints a local install and config report and exits. It does not open a session, does not call a model, and does not fetch the model catalog. Use it when a session does not start, a search fails, or credentials look unset. --profile selects which profile root it inspects, the same as any other launch. Each row is ok, warn, fail or info. The process exits 1 only when a row is fail. Warnings and info rows still exit 0. Extra words after doctor are a usage error (exit 2). A missing daemon is info, not a failure: serve is optional. Credentials fail when there is no BYOK key, no consumer subscription, and no usable hosted plan. The permissions row fails when a deny: entry is not a tool(pattern) string. The detail names deny[n]. Edit that line. Do not delete permissions.yaml, or you drop sibling string denials that still apply. See Permissions. The sandbox row reports the idle sandbox tier and whether a ! bang command is confined, refused, or unsandboxed. A refused bang is warn. An unsandboxed bang is warn. Set SERI_ALLOW_UNSANDBOXED_COMMANDS=false to keep ! inside the OS sandbox when one is available. See Working in the session. The io_uring row is Linux-only. ok means io_uring_setup is rejected. warn means the kernel still allows it, so a seccomp filter that omits io_uring_setup, io_uring_enter, and io_uring_register is bypassable. Other platforms print info.

​
Update

seri update replaces the compiled binary you ran with the latest stable GitHub Release for Seriora-Research/seri-agent. It downloads that platform’s asset and SHA256SUMS, checks the digest, smokes the new file, then swaps it in place. Use it to refresh an existing install. It is not a session and not a billed turn. It refuses a source checkout (bun run dev) and exits 1 with running from source; update with git, or install a release binary. It skips prereleases. Pin a tag with SERI_VERSION the same way the install scripts do: SERI_VERSION=v0.1.0 seri update. If the latest stable release matches seri --version, it prints that the binary is current and exits 0. Extra words after update are a usage error (exit 2). If GitHub has published no stable release, the command exits 1 and says so.