CLI usage

yottacode has two primary entry points:

• yottacode — launch the interactive TUI
• yottacode run "<prompt>" — run one prompt non-interactively

Both use the same agent, tools, provider configuration, memory, and sessions.

Global provider flags

These work for the TUI and run mode.

Two ways to run

yottacode

yottacode run "summarize this repo"

yottacode run "write a changelog entry for the current git diff" > draft.md

yottacode run --format json "triage the failures in test-output.txt" | jq .

{
  "content": "The failure starts in...",
  "tool_calls": [
    {"name": "read_file", "summary": "read_file(test-output.txt)"}
  ],
  "usage": {
    "input_tokens": 1240,
    "output_tokens": 380,
    "cache_read_tokens": 900
  },
  "exit_reason": "ok",
  "error": null,
  "session_id": "20260908-143012.123456"
}

set +e
yottacode run --format json "inspect the failing build" > result.json
run_status=$?
set -e
jq . result.json
exit "$run_status"

Operational progress remains on stderr and never contaminates the JSON stdout object. Errors that occur before an agent turn starts, such as invalid flags or missing provider configuration, retain the normal CLI error output because no run result or session exists yet.

Legacy --json receipt

The older --json flag remains compatible: stdout is still answer-only text and a final receipt is appended to stderr with statuses such as success, approval_required, tests_failed, or iteration_cap. Do not combine it with --format json; new integrations should use the structured stdout contract.

See the five yottacode run recipes for PR descriptions, codemods, test triage, dependency-audit summaries, and changelog drafting.

Setup

yottacode setup

Runs the first-run configuration wizard. It can write ~/.yottacode/config.toml and help configure provider profiles.

Provider commands

yottacode provider list
yottacode provider add openai
yottacode provider use openai
yottacode provider remove old-provider
yottacode provider refresh
yottacode provider refresh openai

Provider profiles live in ~/.yottacode/config.toml as [[providers]] blocks.

Model commands

yottacode model list
yottacode model list --all
yottacode model use <your-model-id>
yottacode model fetch
yottacode model fetch openai

model use updates the active default_model in config. In the TUI, /model <name> switches only the running session.

Diagnostics

yottacode doctor
yottacode doctor --json

doctor prints a grep-friendly report with a top-level summary and consistent sections for provider, GitHub, LSP, media, and sandbox checks. It probes the provider /models endpoint for reachability, auth status, model visibility, provider capabilities, and bounded model-list samples; GitHub can be skipped with --no-github. The JSON form is intended for scripts and keeps the provider fields at the top level for compatibility while adding nested section/status objects.

ChatGPT OAuth

yottacode openai-auth login
yottacode openai-auth status
yottacode openai-auth status --json
yottacode openai-auth logout

These commands manage the openai-auth provider’s browser OAuth credentials and account-specific model list.

GitHub Copilot auth

yottacode copilot-auth login
yottacode copilot-auth models
yottacode copilot-auth models --raw
yottacode copilot-auth status
yottacode copilot-auth status --json
yottacode copilot-auth logout

These commands manage the copilot provider’s GitHub device-code OAuth credentials and model cache. login runs the device code flow and caches available models. models lists cached models and marks plan-gated ones with [upgrade plan].

Sessions

yottacode sessions list
yottacode sessions list --json
yottacode sessions resume <id-or-name>
yottacode sessions resume <id-or-name> --summarized
yottacode sessions rename <id-or-name> <new-name>
yottacode sessions export <id-or-name>
yottacode sessions export <id-or-name> path.md --force
yottacode sessions export <id-or-name> path.jsonl --force

Sessions are saved automatically after completed turns in ~/.yottacode/sessions/. Export paths ending in .jsonl write a schema-versioned structured activity log for team audit and debugging; review it before sharing because prompts, tool args/results, paths, command output, and image metadata can contain sensitive local context.

Memory

yottacode memory list                              # default scope: project
yottacode memory list --scope user
yottacode memory recall --query "testing preferences"
yottacode memory recall --query "deployment" --scope project --top-k 3 --format json
yottacode memory audit                             # read-only curation report
yottacode memory forget --scope <user|project> <name>

Use the TUI /memory picker to edit USER.md / YOTTACODE.md and browse agent-managed memories in vim. See Memory for the full layout and the memory_save / memory_forget tools the agent uses to curate this layer.

Worktrees

yottacode --worktree <name>           # start a session in a git worktree
yottacode -w <name>                   # short form
yottacode run --worktree <name>       # one-shot in a worktree
yottacode worktree list               # list active worktrees
yottacode worktree status             # show worktree state
yottacode worktree remove <name>      # remove a worktree
yottacode worktree prune              # clean up stale worktrees

See Worktrees for the full workflow and .worktreeinclude format.

GitHub setup

yottacode setup github                # interactive PAT setup (or use $GITHUB_TOKEN / gh auth)

See GitHub integration for the full auth chain and available slash commands.

Version

yottacode version