Command line

shelley [global-flags] <command> [command-flags]

Global flags go before the command. Flags take one dash or two (-db and --db are the same). shelley <command> -h prints a command’s flags, though a few commands, noted below, don’t understand -h.

Global flags

Flag	Default	Does
-db PATH	shelley.db	SQLite database: conversations, settings, custom models, MCP servers. Relative to the current directory, so set it.
-config PATH	none	Optional shelley.json. A path that doesn’t exist is ignored.
-default-model ID	none	Default model for the web UI. Overrides default_model in shelley.json. Unset, the first ready model wins.
-predictable-only	off	Use only predictable, a built-in fake model. Free, and useless for real work.
-debug	off	Debug logging.
-disable-gateway	off	Ignore llm_gateway from shelley.json.
-disable-llm-integration	off	Ignore any discovered exe.dev LLM integration.

serve

Starts the web server.

shelley --db ~/.shelley/shelley.db serve --port 9000

Flag	Default	Does
-port N	9000	TCP port. Shelley listens on all interfaces. 0 picks a free port.
-port-file PATH	none	Write the port actually used to this file (handy with -port 0).
-socket PATH	~/.config/shelley/shelley.sock	Unix socket for shelley client and shelley mcp. none disables it, which also breaks the agent’s own shelley mcp calls.
-require-header NAME	none	Reject /api/ and /mcp/ requests over TCP that lack this header. Only checks that it’s present: useful behind a proxy that sets it, not authentication by itself.
-systemd-activation	off	Take the listening socket from systemd (LISTEN_FDS) instead of opening a port.
-banner TEXT	none	Show a banner at the top of the UI, e.g. to mark a demo instance.

The Unix socket is created with mode 0600 and skips the -require-header and cross-origin checks; whoever can open it is trusted. The default socket path follows XDG_CONFIG_HOME if it’s set.

models

Prints the built-in models Shelley would offer with the current API keys, -config, and global flags, without starting the server: ID, provider, API type, base URL, where the credentials came from, and a * on the default. Transcription models, if any, are listed after. Custom models added in the UI live in the database and aren’t shown. No flags of its own.

shelley models

client (experimental)

A command-line client for a running Shelley, connecting over the Unix socket by default. It prints JSON. Its interface may change without notice.

Flag	Does
-url URL	unix:///path, http://host:port, or https://host:port. Defaults to $SHELLEY_SOCKET, else the default socket.
-H 'Name: Value'	Extra request header, repeatable.

Subcommand	Does
chat -p PROMPT	Sends a message, starting a new conversation unless -c ID is given, and prints the conversation ID. Also -model, -cwd, -reasoning, -tool NAME=on|off, -no-tools, -tag, -ephemeral (wait for the turn, then archive), -disable-notifications.
read ID	Prints a conversation’s messages as JSON lines. -wait streams until the turn ends; -full gives complete records; -usage gives token totals including subagents.
list	Lists conversations. -archived, -limit N (default 50), -q QUERY.
search QUERY	Searches slugs and message content. -limit N (default 20).
tag ID [TAG...]	Shows or adds tags; -rm removes, -set replaces.
tags	Tags in use, most used first.
archive ID	Archives a conversation.
help	Detailed help with examples.

ID=$(shelley client chat -cwd ~/src/app -p "run the tests" | jq -r .conversation_id)
shelley client read -wait "$ID"

mcp

Uses the MCP servers registered with Shelley: list, search, call, add, rm, auth, restart. -url (before the subcommand) picks the server, with the same default as client. See MCP servers.

skill

Lists, prints, or creates skills: skill ls, skill cat NAME, skill new NAME. No flags, and -h isn’t recognized. See Skills.

tour

Tools for commit tours, the narrated walkthroughs stored as git notes. Mostly run by the agent, following the commit-tour skill.

Subcommand	Does
tour chunks COMMIT	Prints the commit’s diff as numbered patch fragments, as JSON. -index for a compact index, -text for raw patch text, -only 0,3-5 to pick chunks.
tour scaffold COMMIT	Prints a skeleton tour that covers every chunk.
tour verify COMMIT TOUR.json	Checks a tour against the commit.
tour attach COMMIT TOUR.json	Verifies, then stores the tour as a git note.
tour show COMMIT	Prints the stored tour.

All take -C DIR (default .) for the repository. shelley tour -h isn’t recognized but prints this usage anyway.

unpack-template

shelley unpack-template go ./myapp

Copies a project template into a directory, creating it if needed. There is one template, go: a Go web app with HTTP handlers, SQLite with migrations, and a systemd unit, written with exe.dev VMs in mind. -h lists the templates.

exe-scroll

Runs exe-scroll, a terminal-session program embedded in the binary. Shelley uses it for the web UI’s persistent terminals. Its usage is exe-scroll <socket> [-- command...]: attach to the session at that socket, or start one running the command (default $SHELL). Detach by sending the attaching process SIGUSR2. shelley exe-scroll -h has the details.

dtach

The older persistent-terminal helper, kept so terminal sessions created by previous versions stay attachable. New sessions use exe-scroll.

shelley dtach new -s SOCKET [-cwd DIR] [-cols N -rows N] -- CMD [ARGS...]
shelley dtach attach -s SOCKET

There’s no detach key; close the terminal to detach.

version

Prints version information as JSON. It takes no flags and ignores -h:

{
  "version": "0.1346.914604164",
  "tag": "v0.1346.914604164",
  "commit": "330874c6e28f2ee76dae3c60522342b9610d0d90",
  "commit_time": "2026-10-10T01:54:50Z"
}

The flag definitions are in cmd/shelley/main.go.