# CLI Reference

Yoker provides seven subcommands, auto-generated by Clevis from the config
dataclasses. When no subcommand is given, `chat` is assumed for backward
compatibility.

```bash
yoker --help            # list all subcommands
yoker <subcommand> --help  # show flags for a specific subcommand
```

## `yoker chat` — Interactive REPL

Start the interactive REPL. This is the default subcommand when no subcommand
is given. Runs the bootstrap wizard on first use when no config file exists.

**Usage:**

```bash
yoker chat [OPTIONS]
```

**Key flags** (all Config flags are available — see `yoker chat --help` for
the full list):

| Flag | Effect |
|------|--------|
| `--ui-mode {interactive,batch}` | Select UI handler (default: interactive) |
| `--ui-show-thinking` | Show LLM reasoning trace |
| `--ui-show-tool-calls` | Show tool call details |
| `--ui-show-stats` | Show turn statistics |
| `--with <package>` | Load a plugin package (repeatable) |
| `--agents-definition <path>` | Load an agent definition file |
| `--backend-provider <name>` | LLM provider: ollama, openai, anthropic, gemini |
| `--backend-ollama-model <model>` | Ollama model name |
| `--backend-openai-model <model>` | OpenAI model name |
| `--backend-anthropic-model <model>` | Anthropic model name |
| `--backend-gemini-model <model>` | Gemini model name |

**Examples:**

```bash
yoker                                    # same as `yoker chat`
yoker chat --ui-mode batch               # batch mode for pipelines
yoker chat --with pkgq                   # load a plugin
yoker chat --agents-definition examples/agents/researcher.md
yoker chat --backend-ollama-model qwen3.5:cloud
```

**Batch mode:** reads from stdin, writes response content to stdout. Thinking,
tool calls, errors, and statistics go to stderr. Useful in pipelines:

```bash
printf "What is 2+2?\n" | yoker chat --ui-mode batch
```

## `yoker run <source>` — Run an Agentic Package

Load a source and run it non-interactively. The source's `agent.toml` manifest
specifies which agent to use and what initial prompt to send.

**Usage:**

```bash
yoker run <source> [OPTIONS]
```

**Source types** (auto-detected):

| Type | Example | Detection |
|------|---------|-----------|
| Module | `pkgq` | Fallback |
| GitHub URL | `https://github.com/owner/repo` | URL with scheme |
| Folder | `./my-folder` | Existing directory |
| Zip file | `./my-package.zip` | `.zip` extension, is a file |

**Key flags:**

| Flag | Effect |
|------|--------|
| `--agent <name>` | Override the manifest's agent |
| `--prompt <text>` | Override the manifest's prompt (max 10 KB) |
| `--dry-run` | Resolve and print manifest info without executing |
| `--persist` | Enable context persistence (saves session to JSONL) |
| `--session-id <id>` | Session ID for persistence |
| `--source <source>` | Source to run (positional alternative) |

All Config flags (backend, tools, permissions, etc.) are also available.

**Examples:**

```bash
yoker run pkgq                                       # Python module
yoker run https://github.com/christophevg/pkgq        # GitHub URL
yoker run ./my-folder                                 # local folder
yoker run ./my-package.zip                            # zip file
yoker run pkgq --agent researcher --prompt "analyze"  # override manifest
yoker run pkgq --dry-run                             # preview without executing
yoker run pkgq --persist --session-id my-run          # persist session
```

**Trust gate:** the source must be trusted before code is executed. See the
[Creating Agentic Packages](guides/creating-agentic-packages.md) guide for
the trust model and how to trust a source.

## `yoker loop <source>` — Interval Execution

Run an agentic package at intervals. The source is resolved, trusted, and
loaded once; each iteration sends the same prompt through the agent.

**Usage:**

```bash
yoker loop <source> [OPTIONS]
```

**Key flags** (in addition to all `yoker run` flags):

| Flag | Default | Effect |
|------|---------|--------|
| `--interval <seconds>` | 300 | Seconds between iterations |
| `--max-iterations <n>` | 100 | Stop after N iterations |
| `--max-duration <seconds>` | none | Stop after wall-clock time limit |

**Examples:**

```bash
yoker loop pkgq --interval 60                        # run every 60 seconds
yoker loop pkgq --interval 60 --max-iterations 3     # stop after 3 runs
yoker loop pkgq --persist --session-id loop-1        # reuse context
yoker loop pkgq --max-duration 3600                  # stop after 1 hour
```

**Stopping:** the loop stops on `--max-iterations`, `--max-duration`, 3
consecutive failures (with exponential backoff), or `Ctrl+C` (graceful
shutdown with a summary of completed iterations).

## `yoker inspect <source>` — Read-Only Source Report

Display a human-readable report about a source without executing any code.
No trust gate is required — safe to run on untrusted sources.

**Usage:**

```bash
yoker inspect <source>
```

**Flags:**

| Flag | Effect |
|------|--------|
| `--source <source>` | Source to inspect (positional alternative) |

**Examples:**

```bash
yoker inspect pkgq
yoker inspect ./my-folder
yoker inspect https://github.com/owner/repo
```

**Report contents:**

- **What it contains**: skills (names), agent definitions (names), tools
  (declared `tools_module` — listed but not imported)
- **What it uses**: dependencies from `pyproject.toml`, `tools_module`
  declaration
- **What it does**: the agent and prompt from the manifest's `[run]` section
- **Config overrides**: any config fields the manifest overrides

For module sources, the Python `__YOKER_MANIFEST__` cannot be discovered
without importing the package, so the report notes that trust is required.

## `yoker init` — Generate Configuration

Create a `~/.yoker.toml` configuration file. Interactive mode runs the
bootstrap wizard; non-interactive mode writes a default config.

**Usage:**

```bash
yoker init [OPTIONS]
```

**Flags:**

| Flag | Effect |
|------|--------|
| `--no-interactive` | Write a default config without the wizard |
| `--path <path>` | Write to a custom location (default: `~/.yoker.toml`) |
| `--force` | Overwrite an existing config file |

**Examples:**

```bash
yoker init                          # interactive wizard (default)
yoker init --no-interactive         # write defaults without prompting
yoker init --path ./my-config.toml # write to a custom location
yoker init --force                 # overwrite an existing file
```

Written files always have `chmod 600` permissions. The `--path` flag rejects
forbidden system prefixes (e.g. `/etc`, `/usr`). When overwriting with
`--force` and stdin is a TTY, the user is asked to confirm.

## `yoker config` — Display Effective Configuration

Load the merged config (user TOML + project TOML + CLI args) and print it.
API keys are masked by default.

**Usage:**

```bash
yoker config [OPTIONS]
```

**Key flags:**

| Flag | Effect |
|------|--------|
| `--json` | Output as JSON instead of TOML |
| `--show-path` | Print the config file paths that were found |
| `--reveal` | Show API key values in full (masked by default) |

All Config flags are also available, so CLI overrides are reflected in the
output.

**Examples:**

```bash
yoker config              # print config as TOML
yoker config --json       # print config as JSON
yoker config --show-path  # print config file paths
yoker config --reveal     # show API keys unmasked
yoker config --backend-ollama-model qwen3.5:cloud  # reflect CLI override
```

## `yoker container <source>` — Generate Container Setup

Generate a Dockerfile (or Containerfile for podman) and ignore file for
running a yoker agentic package in a container.

**Usage:**

```bash
yoker container <source> [OPTIONS]
```

**Flags:**

| Flag | Default | Effect |
|------|---------|--------|
| `--source <source>` | — | Source to containerize |
| `--engine {docker,podman}` | docker | Container engine |
| `--output-dir <path>` | `.` | Where to write generated files |
| `--base-image <image>` | `python:3.12-slim` | Base image |
| `--compose` | off | Also generate `docker-compose.yml` |

**Examples:**

```bash
yoker container pkgq                          # generate Dockerfile
yoker container pkgq --engine podman          # generate Containerfile
yoker container pkgq --output-dir ./container/ # custom output directory
yoker container pkgq --compose                # also generate docker-compose.yml
yoker container ./my-folder                    # containerize a folder
yoker container https://github.com/x/y         # containerize a GitHub repo
```

**Security:** the generated Dockerfile uses JSON-array form exclusively for
`RUN`/`ENTRYPOINT` (no shell-form injection risk), includes a non-root `USER`
directive (`USER 1000`), pins the yoker version (`pip install yoker==<version>`),
and does not copy `~/.yoker.toml` or API keys into the image. A
`.dockerignore`/`.containerignore` is generated excluding secrets, `.git`,
`__pycache__`, etc. For GitHub sources, the Dockerfile pins to the resolved
commit SHA.

## Global Behavior

### `--with` Plugin Loading

The `--with <package>` flag loads plugin packages. It is parsed before
subcommand dispatch and works from any subcommand position. Plugin packages
must be trusted in your config (see [Plugins](plugins.md)).

```bash
yoker --with pkgq chat
yoker chat --with pkgq
yoker run pkgq --with other-plugin
```

### Backward Compatibility

When no subcommand is given, `chat` is inserted automatically:

```bash
yoker                              # -> yoker chat
yoker --backend-ollama-model X     # -> yoker chat --backend-ollama-model X
```

### Configuration Discovery

Config files are auto-discovered in this order:

1. `./yoker.toml` (current directory)
2. `~/.yoker.toml` (user home directory)
3. Built-in defaults

Subcommand-specific config sections are also supported. For example, a `[chat]`
section in `yoker.toml` applies only to `yoker chat`, and a `[run]` section
applies only to `yoker run`. If no subcommand section exists, root-level TOML
is used as-is.