reference

you-agent-factory CLI Reference

This directory is the single source of truth for packaged CLI reference topics. Markdown here is embedded into the you binary (docs/reference/embed.go → you docs <topic>). There is no second tree to edit or copy under pkg/cli/docs/.

Maintainer workflow

1. Edit the topic file in this directory (for example docs/reference/config.md).
2. Run make docs-reference-smoke from the repository root.
3. Ship the change. Rebuild or release the CLI when operators need the updated embedded output; do not mirror markdown into another directory.

Use the fixed CLI topic names for quick terminal help, then use the canonical concept owners below when you need the complete customer-facing contract.

Packaged CLI Topics

Terminal / agent readers: cross-references between packaged CLI topics are runnable as you docs <topic> (for example you docs config). The .md links in maintainer tables below point at source files in this directory for editing only; they do not resolve in you docs terminal output.

you docs <topic> accepts these topics:

batch-work remains accepted by the installed CLI as a compatibility alias for the canonical batch-inputs topic. workstation remains accepted as a compatibility alias for the canonical workstations topic.

CLI Output And Diagnostics

Default command output is the customer-facing command result. Commands that emit JSON must keep parseable JSON on stdout, and any troubleshooting diagnostics from --verbose or --debug must use stderr unless an existing command-owned diagnostics stream is explicitly documented.

--verbose is for concise operational context that helps diagnose a command without changing its result. Verbose diagnostics may include paths, endpoint URLs or paths, request or trace IDs, status codes, counts, durations, byte sizes, output paths, and selected option summaries. --debug is for lower-level development diagnostics where a command supports that mode, and debug mode implies verbose command diagnostics.

Verbose and debug diagnostics must not include full prompts, full work payloads, access tokens, full model input text, full successful response bodies, sensitive generated content, or full command stdout or stderr unless an existing explicit failure policy already permits a bounded preview.

CLI verbose diagnostics are separate from service runtime logs controlled by you run --runtime-log-*. Runtime logs are structured service-owned logs; command diagnostics explain the CLI invocation and transport or filesystem work around that invocation.

Canonical Concept Owners

• Config owns work types, work states, top-level factory.json, routing behavior, runtime resources, and portability fields.
• Submitted work owns POST /work, submitted-work tags, and batch cross-links.
• Sessions owns live session discovery, factory query, status API fields, dashboard URL, and --server / --session routing for HTTP client commands.
• Workstations owns workstation kinds, route fields, runtime step behavior, prompt/runtime fields, and workstation-scoped execution settings.
• Workers owns worker types, worker-scoped runtime fields, model/script backend fields, and split workers/<name>/AGENTS.md placement.

Use these canonical concept owners when you need the current contract.

Customer Guide Structure

• Config explains the canonical split factory layout around factory.json, workers/, workstations/, and inputs/.
• Resources explains top-level resource pools and the {name, capacity} requirements consumed by workers or workstations.
• Models and model operations explains MODEL_INVOKE, MODEL_WORKER capabilities, typed model resources, /models, and local or cloud TTS authoring patterns.
• Batch inputs explains the FACTORY_REQUEST_BATCH request shape, watched-file placement, and supported relation types.
• Templates explains the supported Go-template surfaces, the full variable inventory, and the JSON-versus-Markdown quoting rules.
• Mock workers owns --with-mock-workers, the mockWorkers JSON contract, selection fields, and runType outcomes.
• Record and replay owns default recording, generated artifact paths, --record, --replay, --no-record, and incompatible flag combinations.
• Author factories keeps factory sequencing, quick-start run commands, reusable docs/examples/ inputs, and links to the dedicated mock-worker and record/replay guides.
• Author AGENTS.md keeps split-file shape, prompt placement, and prompt-authoring examples.

Related

• Package docs index
• Config
• Sessions
• Submitted work
• Workstations
• Workers
• Resources
• Models and model operations
• Author AGENTS.md
• Batch inputs
• Templates