CLI

Look up the you-agent-factory command groups, how a factory is selected for a run, the global flags every command shares, and where the full published CLI contract lives.

Install

Install the you CLI with the published release entrypoint for your operating system, then configure a provider before the first run. The install page carries the OS commands, the provider step, and the packaged-factory install.

Install you-agent-factory

Commands

Pick a command group by what you are trying to do, and check whether it needs a factory host already listening. Startup forms create the runtime. Session, work, and submit forms address a runtime that already exists. Everything else reads or writes local state.

Command group	Purpose	Factory must already be running?
you init	Configure the default provider and model, or install a packaged factory from the embedded catalog.	No
you run	Load a factory and run the engine. Batch by default; add --continuously to stay alive while idle.	No — this starts the runtime.
you server	Validate and serve the current factory from ./factory/factory.json, opening the dashboard once ready.	No — this starts the runtime.
you factory list / create / update / delete	Manage persisted named factories under one factory root at a time.	No
you factory config validate / expand / flatten	Validate a definition without persisting it, or convert between the single-file and split layouts.	No
you session list / show / create / delete / pause / resume / dispatches	Manage factory sessions and read their durable dispatches on a host.	Yes
you submit / you submit batch	Submit one work item, or upsert a canonical request batch, to a live session.	Yes
you work list / show / move / visualize	Inspect and move work items. Visualizing a batch file reads local JSON instead.	Yes, except visualize
you workers list / acp add / acp delete	Inspect selectable worker integrations and configure Agent Client Protocol providers.	No
you models list / inspect / pull / invoke	Read discovered models and their readiness, pull local models into the managed cache, or invoke one directly.	Yes, except invoke
you mcp serve	Start the Factory Session Model Context Protocol server over stdio for an MCP host.	No
you serve acp	Host you-agent-factory as an Agent Client Protocol agent over stdio for an editor.	No
you docs / you docs <topic>	Print packaged reference markdown from the installed binary.	No

CLI Reference — every published command, flag, and argument

Selecting A Factory

A run needs to know which factory to load, and there are three ways to say so. A named factory is resolved from ./factory first and then from the global factory root. A directory names a factory layout on disk. A portable factory is a single JSON or YAML file or an unambiguous directory, run in place without installing it.

you run --named @you/goal "Ship the login bugfix"
you run --dir factory --work ./docs/examples/startup-work.json
you run --factory ./factory.yaml "Fix the lint issues"

With no selector at all, a run validates the invocation-local ./factory/factory.json as the current factory. It does not bootstrap a missing definition and does not follow another current-factory pointer, so a run in the wrong directory fails before anything starts rather than silently picking something else.

Global Flags

Four flags are available on every command and are written before the subcommand. Structured output emits JSON on stdout while diagnostics stay on stderr, which is what makes the CLI scriptable. The server flag sets the factory API base URI: HTTP client commands target it, and server-enabled runs bind its loopback host and port.

you --json factory list
you --server http://127.0.0.1:7437 session list
you --verbose run --named @you/review "Draft the release notes"

The per-command --port flag is deprecated in favour of the global --server flag. Prefer the base URI: it carries scheme, host, and port in one value and applies uniformly.

Offline Reference

The binary carries its own reference topics and prints them with no network connection and no running host. Twenty-one topics cover authoring factories, runs, configuration, mock workers, record and replay, guards, relationships, work, sessions, orchestrators, JavaScript workflows, MCP, workstations, workers, resources, models, batch inputs, and templates.

you docs
you docs agents

How to make your agent use YOU

Limits And Assumptions

Coverage here is command groups, factory selection, and global flags. Exhaustive per-command flags, arguments, exit codes, and lifecycle state live on the CLI reference, which is projected directly from the installed package contract rather than retyped. HTTP operations live on the API reference.

CLI