Usage — Swival
Description: Usage — Swival documentation

# Usage

Swival operates in two modes: one-shot (the default) and interactive (REPL).

## One-shot mode

Give it a task, let it work, get the result:

    swival "Review this codebase for security issues"

The agent loops through tool calls -- reading files, searching code, reasoning -- until it has a final answer. That answer is printed to stdout. Everything else (turn headers, tool call logs, timing) goes to stderr.

This separation is intentional. You can pipe the output:

    swival -q "Summarize the API surface of src/" > api-summary.txt

The `-q` (or `--quiet`) flag suppresses all diagnostic output on stderr, so you get just the answer.

### Giving the agent more power

By default, Swival can read, write, and search files within the current directory. If you want it to run commands too:

    swival --allowed-commands ls,git,python3 \
        "Create a tool that returns a random number between 0 and 42"

The available commands influence the agent's behavior -- if you allow `bun` and `node`, it'll lean toward JavaScript. Allow `python3` and it'll write Python.

### Exit codes

- `0` -- success, the agent produced an answer
- `1` -- error (couldn't connect to LM Studio, invalid arguments, etc.)
- `2` -- max turns exhausted without a final answer

## Interactive mode (REPL)

    swival --repl

This gives you an interactive session with conversation history that carries across questions. It works like Claude Code or Codex -- ask a question, watch it work, ask a follow-up.

You can also start a REPL with an initial question:

    swival --repl "Look at the project structure and tell me what this does"

### REPL commands

- `/help` -- show available commands
- `/clear` -- reset conversation history (keeps system prompt)
- `/compact` -- compress context by truncating old tool results
- `/compact --drop` -- more aggressive: drops entire middle turns
- `/add-dir <path>` -- grant read/write access to an additional directory
- `/extend` -- double the current max turns limit
- `/extend <N>` -- set max turns to a specific number
- `/continue` -- reset the turn counter and continue the agent loop
- `/exit` or `/quit` -- exit (Ctrl-D works too)

The REPL uses `prompt-toolkit`, so you get command history, history search, and line editing.

## CLI flags

### Model and provider

Flag | Default | Description
--- | --- | ---
`--provider` | `lmstudio` | LLM provider: `lmstudio`, `huggingface`, or `openrouter`
`--model` | auto-discovered | Override model identifier
`--base-url` | `http://127.0.0.1:1234` | Server base URL
`--api-key` | from env | API key (overrides `HF_TOKEN` / `OPENROUTER_API_KEY`)

### Behavior tuning

Flag | Default | Description
--- | --- | ---
`--max-turns` | `100` | Maximum agent loop iterations
`--max-output-tokens` | `32768` | Maximum output tokens per LLM call
`--max-context-tokens` | from model | Requested context length (may trigger model reload)
`--temperature` | `0.55` | Sampling temperature
`--top-p` | `1.0` | Top-p (nucleus) sampling
`--seed` | none | Random seed for reproducible outputs

### Sandboxing

Flag | Default | Description
--- | --- | ---
`--base-dir` | `.` | Base directory for file tools
`--allowed-commands` | none | Comma-separated command whitelist
`--allow-dir` | none | Grant access to extra directories (repeatable)
`--yolo` | off | Disable sandbox and command whitelist entirely

### System prompt and instructions

Flag | Default | Description
--- | --- | ---
`--system-prompt` | built-in | Custom system prompt (replaces default)
`--no-system-prompt` | off | Omit system message entirely
`--no-instructions` | off | Don't load CLAUDE.md or AGENT.md

### Skills

Flag | Default | Description
--- | --- | ---
`--skills-dir` | none | Additional skill directory (repeatable)
`--no-skills` | off | Disable skill discovery

### Output and reporting

Flag | Default | Description
--- | --- | ---
`-q` / `--quiet` | off | Suppress all diagnostics; only print the final result
`--report FILE` | off | Write a JSON evaluation report instead of stdout
`--reviewer EXE` | off | Run external reviewer after each answer (see Reviews)
`--no-history` | off | Don't write responses to `.swival/HISTORY.md`
`--color` | auto | Force ANSI color on stderr
`--no-color` | auto | Disable ANSI color on stderr

See Reports for the full report schema, timeline event types, and benchmarking workflows. See Reviews for the reviewer protocol and how to build a reviewer script.