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.
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:
yoker chat [OPTIONS]
Key flags (all Config flags are available — see yoker chat --help for
the full list):
Flag |
Effect |
|---|---|
|
Select UI handler (default: interactive) |
|
Show LLM reasoning trace |
|
Show tool call details |
|
Show turn statistics |
|
Load a plugin package (repeatable) |
|
Load an agent definition file |
|
LLM provider: ollama, openai, anthropic, gemini |
|
Ollama model name |
|
OpenAI model name |
|
Anthropic model name |
|
Gemini model name |
Examples:
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:
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:
yoker run <source> [OPTIONS]
Source types (auto-detected):
Type |
Example |
Detection |
|---|---|---|
Module |
|
Fallback |
GitHub URL |
|
URL with scheme |
Folder |
|
Existing directory |
Zip file |
|
|
Key flags:
Flag |
Effect |
|---|---|
|
Override the manifest’s agent |
|
Override the manifest’s prompt (max 10 KB) |
|
Resolve and print manifest info without executing |
|
Enable context persistence (saves session to JSONL) |
|
Session ID for persistence |
|
Source to run (positional alternative) |
All Config flags (backend, tools, permissions, etc.) are also available.
Examples:
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 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:
yoker loop <source> [OPTIONS]
Key flags (in addition to all yoker run flags):
Flag |
Default |
Effect |
|---|---|---|
|
300 |
Seconds between iterations |
|
100 |
Stop after N iterations |
|
none |
Stop after wall-clock time limit |
Examples:
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:
yoker inspect <source>
Flags:
Flag |
Effect |
|---|---|
|
Source to inspect (positional alternative) |
Examples:
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_moduledeclarationWhat it does: the agent and prompt from the manifest’s
[run]sectionConfig 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:
yoker init [OPTIONS]
Flags:
Flag |
Effect |
|---|---|
|
Write a default config without the wizard |
|
Write to a custom location (default: |
|
Overwrite an existing config file |
Examples:
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:
yoker config [OPTIONS]
Key flags:
Flag |
Effect |
|---|---|
|
Output as JSON instead of TOML |
|
Print the config file paths that were found |
|
Show API key values in full (masked by default) |
All Config flags are also available, so CLI overrides are reflected in the output.
Examples:
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:
yoker container <source> [OPTIONS]
Flags:
Flag |
Default |
Effect |
|---|---|---|
|
— |
Source to containerize |
|
docker |
Container engine |
|
|
Where to write generated files |
|
|
Base image |
|
off |
Also generate |
Examples:
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).
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:
yoker # -> yoker chat
yoker --backend-ollama-model X # -> yoker chat --backend-ollama-model X
Configuration Discovery
Config files are auto-discovered in this order:
./yoker.toml(current directory)~/.yoker.toml(user home directory)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.