# Using the CLI

This page is about running `morphy` from your shell. For the interactive terminal interface
(panels, keyboard, slash commands), see the [Terminal Interface (TUI)](tui.md).

## Ways to run

```bash
morphy                         # interactive TUI (default) — see tui.md
morphy "task description"      # one‑shot: run a task and exit
morphy --server                # run as a JSON‑RPC server (for apps/integrations)
morphy --scheduler             # run background scheduled jobs
morphy --help                  # full list of options
morphy --version               # print version
```

## Common options

| Option | Meaning |
| --- | --- |
| `-m, --model <model>` | Model to use |
| `-p, --provider <name>` | Provider: `anthropic`, `openai`, `google`, `openrouter`, `z.ai`, `chutes`, `moonshot`, `minimax`, `auto`, … |
| `-d, --cwd <path>` | Working directory (default: current) |
| `--mode <mode>` | Permission mode: `safe`, `normal`, `auto`, `yolo` |
| `--run <mode>` | Run mode: `agent`, `subagents`, `swarm` (see [Run Modes](run-modes.md)) |
| `-a, --agents <n>` | Number of agents (swarm/subagents) |
| `-c, --cycles <n>` | Maximum cycles |
| `--thinking <mode>` | Reasoning: `off`, `on`, `adaptive` |
| `--reasoning-effort <e>` | Effort: `low`, `medium`, `high`, `xhigh`, `max`, `minimal` |
| `--budget <usd>` | Stop when the known LLM cost reaches this amount |
| `--session <name>` | Session name for one‑shot runs |
| `--json` | Output the result as JSON (one‑shot only) |
| `-v, --verbose` | Show detailed activity |

Run `morphy --help` for the complete list.

## One‑shot mode

Run a task and exit, without opening the interface — ideal for scripts and automation:

```bash
morphy "summarize what changed in this folder today"
morphy -p anthropic -m claude-opus-4-8 "write a release note from the latest commits"
morphy --json "list the TODOs in this project" > todos.json
```

Combine with `--run` to use [subagents or a swarm](run-modes.md), and `--budget` to cap cost.

## Interactive mode

Running `morphy` with no task opens the **TUI** — the full interactive chat interface. It's
documented on its own page: [Terminal Interface (TUI)](tui.md).

## Server and scheduler (advanced)

```bash
morphy --server                  # stdio JSON‑RPC (used by the desktop app and editor plugins)
morphy --server --transport ws   # WebSocket on 127.0.0.1:7777
morphy --scheduler               # run saved scheduled jobs in the background
```

Most people never start these by hand. See [Configuration](configuration.md#server-mode-advanced).

## Permission modes

Morphy asks before doing risky things, according to the active mode:

| Mode | Behavior |
| --- | --- |
| `safe` | Most restrictive — asks before almost any action |
| `normal` | Balanced (default) — asks before destructive actions |
| `auto` | Runs most actions automatically, still guards the dangerous ones |
| `yolo` | No prompts — fully autonomous (use with care) |

Set it with `--mode <mode>` on the command line, or `/mode` inside the interface.

## Reasoning

Models that support "thinking" can reason before answering. Use `--thinking` and
`--reasoning-effort` on the command line (or `/thinking` and `/effort` in the interface). More
reasoning can improve hard tasks at the cost of more tokens.