# Command line

> Every shelley subcommand and flag, from the binary's own help.

```text
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](/docs/config). 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.

```sh
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.

```sh
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. |

```sh
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](/docs/mcp).

## skill

Lists, prints, or creates skills: `skill ls`, `skill cat NAME`,
`skill new NAME`. No flags, and `-h` isn't recognized. See
[Skills](/docs/skills).

## tour

Tools for [commit tours](/docs/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

```sh
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.

```text
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`:

```json
{
  "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](https://github.com/boldsoftware/shelley/blob/main/cmd/shelley/main.go).