Skip to content

cli.md

Latest commit

 

History

History
313 lines (231 loc) · 9.86 KB

cli.md

File metadata and controls

313 lines (231 loc) · 9.86 KB
Raw

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
--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:

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 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:

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
--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:

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 <source> 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_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:

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:

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
--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:

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 <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:

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:

  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.