# CLI Commands

## Top-level dispatch

`agen` parses `os.Args[1]` and dispatches to one of the subcommands below. With no subcommand it attaches the TUI (and fork-execs a daemon if none is running); with a non-TTY stdin it serves MCP JSON-RPC over standard I/O instead. Since v1.2.0 the TUI runs no agents itself: it sends every request to the daemon over `~/.config/agenvoy/daemon.sock` and reconnects every 5 seconds while the daemon is down.

```bash
agen                       # Attach TUI; spawn daemon if not running
agen stop                  # Stop the daemon
agen update                # Download the latest release and rebuild
agen --daemon              # Start the daemon directly
agen -p <prompt> [flags]   # Send one prompt through POST /v1/send (v1.3.9)
```

That is the whole surface. Any other first argument that does not start with `-` prints the usage block and exits 1. The one-shot `agen cli <input>` / `agen run <input>` forms were removed; since v1.3.9 `agen -p` covers that use as a thin client of `POST /v1/send`.

## One-shot prompt (`agen -p`)

`agen -p <prompt>` starts the daemon when needed (and waits up to 30 s for its port), sends one request to `POST /v1/send` in a new `temp-` session, and prints the reply. With an empty `-p` the prompt is read from stdin; arguments left after `-p <prompt>` are rejected (exit 2), so quote the prompt. It always sends `enable_edit` and `enable_sandbox`, so the run is in API auto mode and never prompts.

| Flag | `/v1/send` field | Default |
|---|---|---|
| `-m`, `--model` | `model` | `auto` |
| `-r`, `--reasoning` | `reasoning` | `medium` |
| `--stream` | `stream` | off |
| `--work-dir` | `work_dir` | current directory; relative paths resolve from it |
| `--allow-edit` | `enable_edit` | off (read-only) |
| `--skip-sandbox` | `enable_sandbox` (inverted) | off (sandboxed) |

With `--stream`, model, tool and thinking lines go to stderr as `⏵ Model(...)`, `⏵ <Tool>(...)` and `✻ ...`, and the reply streams to stdout. An error exits 1, a cancel (Ctrl+C) exits 130, and a stream that closes before the run finishes exits 1. A cancel stops only the client; the daemon still finishes the task.

`agen --enable-claude-code` was Removed in v1.2.3: the `claude-code` provider is enabled whenever the daemon finds the `claude` binary on its `PATH`.

The short-lived `agen startup <enable|disable>` subcommand was removed; toggle launch-on-login with **Startup on login** in the TUI `/config`.

Model, session, and MCP management live in the TUI (`/model`, `/session`, `/new`, `/mcp`), the web dashboard at `http://127.0.0.1:17989`, and the local HTTP API — there are no `agen model` / `agen session` / `agen mcp` subcommands.

### `agen stop`

SIGTERM every running `agen --daemon` process (found through the process list, plus the one in the runtime record), not only the recorded one, then clear the runtime record. Prints `No daemon running.` and exits 0 when nothing is alive; a stale PID record is cleared instead of killed.

### `agen update`

Always-overwrite update to the latest release. Downloads `https://agenvoy.com/scripts/update.sh` into `agenvoy-update-*.sh` in the system temp directory (`$TMPDIR`), executes it with `bash`, and removes the temp file on completion (SIGINT / SIGTERM also clean up). The running daemon keeps the old binary inode — run `agen stop` and re-attach to pick up the new build.

## Modes

Press `Shift+Tab` in the TUI to toggle auto mode (`safe` ↔ `auto`), `Shift+F` for fast mode, `Shift+G` for `CLAUDE.md` / `AGENTS.md` injection (v1.2.0), and `Shift+P` to set the work directory (v1.3.0). A line starting with `!` runs as a shell command in that directory and its result goes to the agent (v1.3.0). Auto mode is session-local: the TUI starts in `auto` when its working directory is a subdirectory of `$HOME` (not `$HOME` itself, not a denied or sensitive path) and in `safe` otherwise. `POST /v1/send` has no `allow_all` field; auto mode is a TUI toggle only. See the TUI Guide for the full shortcut and slash-command list.

## Configuration

Runtime limits live in `~/.config/agenvoy/config.json` under `limits`; there are no environment-variable overrides. See the Configuration page.