CLI

Every you command published by the installed CLI contract, with its arguments, flags, and examples.

Filter CLI commands

Command path

Lifecycle

Visibility

you

Run and manage CPN-based workflow factories

What: CPN-based workflow factory CLI for running factories, submitting work, and inspecting live sessions. How to use: Run you run --work ./docs/examples/startup-work.json to start the exact Current Factory at ./factory/factory.json with explicit Work and no local server. Use you server to serve that Current Factory API and dashboard continuously, or add --with-server or --with-site to own a server only for one run. See you <cmd> --help for subcommand details. Agents: Start with you docs agents for orientation, you submit or you submit batch to enqueue work, and you session list to confirm a live factory. Run you docs for all packaged reference topics. Use --verbose or --debug for stderr diagnostics; full policy in you docs.

Flags

Flag	Type	Default	Description
--debug, -d	bool	—	emit lower-level command diagnostics where supported (implies --verbose)
--json	bool	—	emit structured JSON on stdout for supported commands; diagnostics remain on stderr
--server	string	http://localhost:7437	factory API base URI (http:// or https://); HTTP client commands target this URI, while you server and server-enabled runs bind its loopback host and port
--verbose, -v	bool	—	emit concise command diagnostics to stderr

Example

you run --work ./docs/examples/startup-work.json
you docs agents

you config

#you-config

Configuration command guide

Route configuration tasks to their canonical commands. Use `you init` to configure provider/model defaults. Use `you factory config` to validate or transform Factory definitions. Normal runtime initialization materializes packaged/default Factories automatically.

Example

you init --provider codex
you factory config validate ./factory.json

you docs

#you-docs

Print packaged markdown reference topics

Print packaged markdown reference topics from the installed binary. Run without a topic to print the quick-start blurb and packaged docs index. Use one supported topic argument to print the authored markdown page with no wrapper formatting.

Arguments

Argument	Type	Notes
<topic>	string	Optional · One of agents, authoring-factories, run, config, mock-workers, record-replay, guards, relationships, work, sessions, orchestrators, javascript-workflows, mcp, workstations, workstation, workers, resources, models, batch-inputs, batch-work, templates

Example

you docs
you docs agents
you docs run

you init

#you-init

Configure provider and model defaults

Configure the default model provider and optional model used for worker execution, or install a packaged Factory from the embedded catalog. Supply --provider for non-interactive provider/model setup. Use --package to install a built-in packaged Factory into the named Factory root (default: the global catalog under your home directory).

Flags

Flag	Type	Description
--dir	string	named Factory root directory for packaged installation
--format	string	authored root definition format for the installed packaged Factory
--model	string	optional non-empty free-form default model identifier
--package	string	public packaged Factory name to install from the embedded catalog
--provider	string	registered default model provider (required for non-interactive setup)
--replace	bool	replace an existing packaged Factory directory when the target already exists

Example

you init --provider codex
you init --provider claude --model claude-sonnet-4-5
you init --package @you/goal
you init --package @you/goal --dir ./factories --format yaml --replace

you run

#you-run

Load workflow and run the factory engine

Without an explicit --dir, --named, or --factory selector, you run validates the exact invocation-local ./factory/factory.json as the Current Factory; it does not bootstrap a missing Factory or follow another current-factory pointer. Run you run --work ./docs/examples/startup-work.json to submit explicit default Work; Factory directory runs can consume factory/inputs/task/default while active. Missing and invalid definitions fail before runtime, listener, or browser activation. Ordinary batch, continuous, named, portable Factory, replay, mock-worker, and JavaScript runs start no HTTP listener. Add --with-server to serve the Current Factory API for exactly the run lifetime without opening a browser, or --with-site to imply that server and open the embedded dashboard once after readiness. Server-enabled runs bind only the loopback host and preferred port from global --server, advance monotonically through port 65535 on collisions, report the actual bound URL, and join the listener before returning. Default execution uses batch mode and exits after idle completion. Use --continuously to keep the factory alive while idle until you cancel it. Use --with-mock-workers with an optional JSON config path for deterministic outcomes. Use --worktree <name> to create or reuse a Git worktree under the invocation working directory and execute every worker dispatch in that checkout, independent of provider. Use --quiet to suppress dashboard output for scripted or CI-oriented runs. Use --skip-permissions to request an invocation-only unsafe permission bypass for agent workers without changing persisted factory configuration. Normal live runs record by default unless you pass --no-record. Replay artifacts are sensitive and can contain prompts, payloads, stdout, stderr, and diagnostic metadata. Use --named with a persisted canonical factory name to resolve project-local factories before global built-ins under ~/.you-agent-factory/factories. Built-ins materialize lazily into that global root on first use and stay editable on disk. Use --factory with a JSON, YAML, or JavaScript Factory source. Supported selectors are --dir, --named, and --factory. Selected Factories can define custom invocation arguments; run you run --named <factory> --help or you run --factory <factory.yaml> --help to inspect signature-backed usage while keeping existing run-level flags available. In Factory invocation mode, provide either trailing positional text or piped stdin text, or use signature-defined file, repeated, and defaulted inputs; conflicting positional text and stdin return INVOCATION_INPUT_SOURCE_CONFLICT. Named-Factory selection lives in you docs authoring-factories; invocation behavior lives in you docs run and you docs sessions; model choices live in you docs models. The common ACP workflow is `you run --named @you/goal --provider cursor-acp --model auto "Describe the task"`. Run-level --provider selects modelProvider and --model selects an optional model within that provider. Supported one-shot text invocations use the ordered response stream by default; use --output primary for final-result-only stdout. Global --json with response-stream selects NDJSON. Quiet conflicts with global JSON and explicit --output. Failures use one standard ErrorResponse on stderr. Runtime logs are structured JSON rolling files grouped by UTC start date under the selected log root; environment details are record-channel diagnostics only, and system logs include command stdout/stderr only on command failures. Runtime metrics are a separate structured JSONL operational channel with independent rolling files.

Arguments

Argument	Type	Notes
<invocation-input…>	string	Optional · Repeatable · Reads from cli, stdin

Flags

Flag	Type	Default	Description
--continuously	bool	—	keep the factory alive while idle until cancelled
--dir	string	factory	factory base directory
--factory	string	—	path to a JSON or YAML Factory file, or an unambiguous Factory directory, for portable one-shot runs; use positional text or piped stdin for the invocation input
--model	string	—	override the optional model selected within the provider for this run
--named, -a	string	—	canonical persisted factory name resolved from ./factory before ~/.you-agent-factory/factories; built-ins materialize there on first use and remain editable
--no-record	bool	—	disable the default replay artifact for this invocation
--output	string	—	invocation stdout mode: response-stream (default for one-shot text invocations) or primary for final-result-only output
--provider	string	—	override the worker modelProvider for this run (for example cursor-acp)
--quiet	bool	—	suppress dashboard output for quiet or CI-oriented runs
--record	string	—	path to write a replay artifact for this run; replay artifacts are sensitive, and default live runs record automatically unless --no-record is used
--replay	string	—	path to replay an existing sensitive replay artifact
--skip-permissions	bool	—	request an invocation-only unsafe permission bypass for agent workers without changing persisted factory configuration
--with-mock-workers	string	—	enable mock-worker execution with an optional mock-workers JSON config path
--with-server	bool	—	serve the Current Factory API for the lifetime of this run without opening a browser
--with-site	bool	—	serve the embedded dashboard and open it once after listener readiness
--work	string	—	path to initial FACTORY_REQUEST_BATCH JSON file to submit
--worktree	string	—	create or reuse a Git worktree under the invocation working directory and execute this run in its checkout

Example

# Start the current Factory with explicit Work.
you run --work ./docs/examples/startup-work.json

# Run an existing factory once in explicit batch mode.
you run --dir factory --work ./docs/examples/startup-work.json

# Run a persisted named factory from any working directory.
you run --named @you/tts --output primary "Read the release summary."

# Run a portable JSON or YAML Factory with a one-shot prompt (see handlingBehavior DEFAULT).
you run --factory ./factory.yaml "Fix the lint issues"

# Pipe invocation input via stdin (default primary-result stdout).
echo "Ship the login bugfix" | you run --named @you/goal

# Opt into ordered canonical Factory Event progress instead of primary-result-only stdout.
you run --named @you/goal --output response-stream "Ship the login bugfix"

you server

#you-server

Serve the Current Factory API and dashboard

Validate and serve the exact Current Factory from ./factory/factory.json. The listener remains loopback-only, opens the embedded dashboard once after readiness, and runs until cancellation.

Example

you server
you --server http://127.0.0.1:7437 server

you factory

#you-factory

Inspect and manage factory definitions

Inspect live factory runtime state and manage persisted named factories. Subcommands: query show the current active factory from a running service list list persisted named factories under a factory root config inspect and transform factory configuration create create a named factory from factory.json update replace an existing named factory from factory.json replace-current persist the live current factory from a running service delete remove an unused named factory from disk Use query against a running service. Use config validate, flatten, and expand for factory configuration inspection and transformation. Use list, create, update, and delete for on-disk named factories under --dir (default factory/). Use replace-current with global --server and --session like query to persist the live current factory.

Example

you factory query
you factory config validate ./factory.json
you factory list

you factory config

#you-factory-config

Inspect and transform factory configuration

Subcommands: validate validate a factory.json payload or factory directory flatten write canonical single-file factory config to stdout expand write split factory config layout beside the input file Use validate before create or update. Use flatten and expand to move between single-file and split-layout factory directories.

Example

you factory config validate ./factory.json
you factory config flatten ./factory
you factory config expand ./factory.json

you factory config expand

#you-factory-config-expand

Write split factory config layout

The path may be a standalone factory.json file or a factory directory containing factory.json. The command writes canonical factory.json plus workers and workstations directories beside the input file.

Arguments

Argument	Type	Notes
<factory.json>	string	Required

Example

you factory config expand ./factory.json

you factory config flatten

#you-factory-config-flatten

Write canonical single-file factory config

The path may be a factory directory containing factory.json or a standalone factory.json file. The command writes camelCase canonical JSON to stdout.

Arguments

Argument	Type	Notes
<factory-path>	string	Required

Example

you factory config flatten ./factory

you factory config validate

#you-factory-config-validate

Validate a factory config without persisting it

Validate a factory.json payload or factory directory through the shared validate-only factory contract used by POST /factory-validations. Human output lists authored worker and workstation runtime taxonomy values and prints blocking validation targets with inference, agent, script, or poller terminology when worker/workstation pairings are incompatible.

Arguments

Argument	Type	Notes
<factory-path>	string	Required

Example

you factory config validate ./factory.json
you factory config validate ./factory
you --json factory config validate ./factory.json

you factory create

#you-factory-create

Create a named factory from a config file

Create a new named factory from an existing factory.json file. The command validates the payload, materializes a new named factory layout under the selected factory root, and refuses to overwrite an existing factory name.

Arguments

Argument	Type	Notes
<name>	string	Required

Flags

Flag	Type	Default	Description
--dir	string	factory	factory root directory containing named factories
--fromrequired	string	—	path to an existing factory.json payload (required)
--set-current	bool	—	update .current-factory to the created name

Example

you factory create staging --from ./factory.json
you factory create staging --from ./factory.json --set-current
you --json factory create staging --from ./factory.json

you factory delete

#you-factory-delete

Delete a persisted named factory

Delete a persisted named factory from disk. The command removes the named factory directory under the selected factory root after validation. It refuses to delete the factory currently selected by .current-factory; switch the current pointer to another factory first.

Arguments

Argument	Type	Notes
<name>	string	Required

Flags

Flag	Type	Default	Description
--dir	string	factory	factory root directory containing named factories

Example

you factory delete staging
you factory delete staging --dir my-factory

you factory list

#you-factory-list

List persisted named factories

List persisted named factories stored under a factory root. By default the command lists project-local named factories from ./factory and writes a human-readable table with each factory name, on-disk directory, and whether it is selected by .current-factory. Global built-ins and customer-edited shared factories live under ~/.you-agent-factory/factories and are listed only when you point --dir there explicitly. The command lists exactly one root at a time and never merges project-local and global entries. Use global --json for scripting output.

Flags

Flag	Type	Default	Description
--dir	string	factory	factory root directory containing named factories

Example

you factory list
you factory list --dir ~/.you-agent-factory/factories
you --json factory list --dir my-factory

you factory query

#you-factory-query

Show the current active factory

Show the current active factory from a running you-agent-factory service. By default the command writes a human-readable table with the current factory name and runtime-identifying fields. Use global --json for the API-shaped current-factory payload, and use global --server to target the same factory API base URI as work list and submit. Run you session list to discover live session ids when routing other commands with --session.

Example

you factory query
you --json factory query
you --server http://localhost:9090 --json factory query

you factory replace-current

#you-factory-replace-current

Persist the live current factory from a running service

Read the session current factory from a running service and persist it with PUT. The command uses global --server and --session like factory query.

Flags

Flag	Type	Description
--session	string	target one live factory session; omit to use the default compatibility session

Example

you factory replace-current
you --json factory replace-current --session session-beta

you factory update

#you-factory-update

Update an existing named factory from a config file

Replace an existing named factory from an existing factory.json file. The command validates the payload, atomically replaces the named factory layout under the selected factory root, and leaves .current-factory unchanged when it already points at the updated name.

Arguments

Argument	Type	Notes
<name>	string	Required

Flags

Flag	Type	Default	Description
--dir	string	factory	factory root directory containing named factories
--fromrequired	string	—	path to an existing factory.json payload (required)

Example

you factory update staging --from ./factory.json
you --json factory update staging --from ./factory.json

you mcp

#you-mcp

Model Context Protocol servers for Factory Session tools

Example

you mcp serve

you mcp serve

#you-mcp-serve

Start the Factory Session MCP stdio server

Start the dynamic workflow Factory Session MCP server over stdio. Hosts launch this command as a child process and communicate through newline-delimited JSON-RPC on stdin and stdout. The default backing service is the deterministic durable session fixture catalog used by workflow CLI commands. Use --runtime to select the shared durable JavaScript runtime execution service instead of the fixture catalog. Runtime mode requires workflow sources to resolve from the MCP host working directory or an explicit --project-root. Set the MCP host working directory to the project root where workflow sources and the fixture catalog resolve. See `you docs mcp` for host configuration, serve modes, smoke, and troubleshooting.

Flags

Flag	Type	Description
--fixture-catalog	string	optional path to durable-session contract fixtures; defaults to the catalog discovered from the current working directory
--project-root	string	project root for workflow source resolution in --runtime mode; defaults to the current working directory
--runtime	bool	select the shared durable JavaScript runtime execution service instead of the fixture catalog

Example

you mcp serve
you mcp serve --fixture-catalog ./pkg/transports/http/testdata/durable-session-contract-fixtures.json
you mcp serve --runtime

you models

#you-models

Inspect discovered models from a running service

Inspect discovered models from a running infinite-you service. Use list to discover model identifiers, inspect to view one model's readiness and capabilities, invoke to call a discovered model directly through the shared in-process bootstrap, and pull to populate the managed local-model cache for supported local assets.

Example

you models list
you models inspect OMNIVOICE_Q4_K_M
you models invoke OMNIVOICE_Q4_K_M --operation TTS --text "hello" --output ./speech.wav

you models inspect

#you-models-inspect

Inspect one discovered model

Inspect one discovered model from GET /models/{model_name}. Human output prints readiness, lifecycle, capabilities, and diagnostics for the named model. Use global --json for API-shaped output and global --server to target a non-default factory API base URI.

Arguments

Argument	Type	Notes
<model-name>	string	Required

Example

you models inspect OMNIVOICE_Q4_K_M
you --json models inspect OMNIVOICE_Q4_K_M

you models invoke

#you-models-invoke

Invoke one discovered model

Invoke one discovered model through the shared in-process bootstrap. Requires a model name, an uppercase --operation, non-empty --text, and either --output for streamed audio or global --json for structured invocation metadata. Readiness-gated execution uses the current factory configuration without starting a full workflow.

Arguments

Argument	Type	Notes
<model-name>	string	Required

Flags

Flag	Type	Default	Description
--operation	string	TTS	uppercase model operation to invoke TTS
--output	string	—	path for streamed model output
--text	string	—	text input for the selected model operation

Example

you models invoke OMNIVOICE_Q4_K_M --operation TTS --text "Read the release summary." --output ./speech.wav
you --json models invoke OMNIVOICE_Q4_K_M --operation TTS --text "Read the release summary."

you models list

#you-models-list

List discovered models

List discovered models from GET /models on the configured service. Human output summarizes provider locality, supported operations, managed-runtime readiness, and resource counts. Use global --json for API-shaped output and global --server to target a non-default factory API base URI.

Example

you models list
you --json models list

you models pull

#you-models-pull

Pull one discovered local model into the managed cache

Pull one discovered local model into the managed cache through POST /models/{model_name}/pull. Human output reports pull outcome, readiness, cache path, revision, and downloaded files. Use global --json for API-shaped output and global --server to target a non-default factory API base URI.

Arguments

Argument	Type	Notes
<model-name>	string	Required

Example

you models pull OMNIVOICE_Q4_K_M
you --json models pull OMNIVOICE_Q4_K_M

you serve

#you-serve

Host You as a protocol server

Host You as a protocol server for an external client. See `you serve acp --help` for the ACP stdio agent surface.

Example

you serve acp

you serve acp

#you-serve-acp

Host You as an ACP agent over stdio

Host You as an Agent Client Protocol (ACP) agent over stdio. ACP clients (editors and IDEs) launch this command as a child process and exchange newline-delimited JSON-RPC on stdin and stdout. Diagnostics and sanitized startup or serve failures are written to stderr; stdout carries only complete ACP protocol frames. Cleanly closing stdin (EOF) ends the connection successfully. This command hosts the same production ACP server the process composes through root.BuildProcess; it constructs no second service graph, Chat Sessions service, Factory Sessions service, or transport graph, and it does not start the HTTP or dashboard server. This is distinct from `you workers acp add|delete`, which configures You's own use of external ACP-speaking provider agents, and from `you mcp serve`, which hosts the unrelated Model Context Protocol tool server.

Example

you serve acp

you session

#you-session

List, open, and close factory sessions on a running host

Manage factory sessions on a running you-agent-factory service. Subcommands: list list live workspace sessions or durable Factory Sessions with --scope live|persisted|all show show one live or durable Factory Session from GET /factory-sessions/{session_id} dispatches list durable Factory Session dispatches from GET /factory-sessions/{session_id}/dispatches pause pause one live or durable Factory Session through POST /factory-sessions/{session_id}/pause resume resume one paused live or durable Factory Session through POST /factory-sessions/{session_id}/resume create open another live session from a folder path delete close a live session by session id Durable list output uses Factory Session status, source identity, result availability, progress, and action availability. Session commands use the same default --port as work list. Use --json to emit API-shaped responses on stdout; diagnostics stay on stderr when --verbose or --debug is set.

Example

you session list
you session show session-beta
you session pause

you session create

#you-session-create

Open a live factory session from a folder

Open another live factory session from a folder path via POST /factory-sessions. Use --dir to provide the folder path. Optional --init-new-factory and --validate-only map to the API request fields and are mutually exclusive. Use --target-kind and --target-name when the folder exposes multiple runnable targets. Use --json to emit OpenFactorySessionResponse on stdout; diagnostics stay on stderr when --verbose or --debug is set.

Arguments

Argument	Type	Notes
<arg0…>	stringArray	Optional · Repeatable · Reads from cli

Flags

Flag	Type	Default	Description
--dirrequired	string	—	folder path to open as a live factory session
--init-new-factory	bool	—	write the default init scaffold at --dir and open a live session
--port	int	7437	HTTP server port
--target-kind	string	—	target kind when disambiguating runnable factories (default or named)
--target-name	string	—	named target when --target-kind is named
--validate-only	bool	—	validate the folder and optional target without creating a live session

Example

you session create --dir /workspace/fleet
you session create --dir /workspace/fleet --validate-only
you session create --dir /workspace/fleet --target-kind named --target-name beta

you session delete

#you-session-delete

Close a live factory session

Close one live factory session via DELETE /factory-sessions/{session_id}. Use the same --port selection as session list. Use --json to emit a JSON confirmation on stdout.

Arguments

Argument	Type	Notes
<session-id>	string	Required · Reads from cli

Flags

Flag	Type	Default	Description
--port	int	7437	HTTP server port

Example

you session delete session-beta

you session dispatches

#you-session-dispatches

List durable Factory Session dispatches

List durable Factory Session dispatches from GET /factory-sessions/{session_id}/dispatches. Human output uses FactorySession, Dispatch, and FactoryArtifact vocabulary for dispatch id, status, kind, label, and output artifact ids. The command requires a durable dur-sess-* session id. Use global --json for the API-shaped ListFactorySessionDispatchesResponse and global --server to target the same factory API base URI as session show and session resume.

Arguments

Argument	Type	Notes
<session-id>	string	Required · Reads from cli

Flags

Flag	Type	Description
--phase	string	filter by exact Dispatch phase
--status	string	filter by canonical Dispatch status

Example

you session dispatches dur-sess-js-interrupted-001
you --json session dispatches dur-sess-js-interrupted-001

you session list

#you-session-list

List live and durable factory sessions

List factory sessions for the requested scope. live returns workspace sessions kept open by the running host. persisted returns durable Factory Sessions from the deterministic provider loopback. all returns both live workspace sessions and durable Factory Sessions. Human output prints the legacy live-session table for workspace rows and a durable Factory Session table with status, source identity, result availability, progress, and actions. Use --json to emit ListFactorySessionsResponse on stdout.

Arguments

Argument	Type	Notes
<arg0…>	stringArray	Optional · Repeatable · Reads from cli

Flags

Flag	Type	Default	Description
--port	int	7437	HTTP server port
--scope	string	live	session list scope: live, persisted, or all

Example

you session list
you session list --scope persisted
you session list --scope all --json

you session pause

#you-session-pause

Pause one live or durable Factory Session

Pause one live or durable Factory Session through POST /factory-sessions/{session_id}/pause. Human output reports paused, already-paused, invalid-state, not-found, or unreachable-host outcomes using Factory Session terminology. Omit session-id to target the default compatibility session (~default), pass a named live session id such as session-beta, or pass a durable session id from `you session list --scope all`. Use global --json for the API-shaped FactorySessionLifecycleControlResponse and global --server to target the same factory API base URI as workflow status and session show.

Arguments

Argument	Type	Notes
<session-id>	string	Optional · Reads from cli

Example

you session pause
you session pause session-beta
you session pause dur-sess-js-run-n-001
you --json session pause session-beta

you session resume

#you-session-resume

Resume one paused live or durable Factory Session

Resume one paused live or durable Factory Session through POST /factory-sessions/{session_id}/resume. Human output reports resumed, already-running, invalid-state, not-found, or unreachable-host outcomes using Factory Session terminology. Omit session-id to target the default compatibility session (~default), pass a named live session id such as session-beta, or pass a durable session id from `you session list --scope all`. Use global --json for the API-shaped FactorySessionLifecycleControlResponse and global --server to target the same factory API base URI as workflow status and session show.

Arguments

Argument	Type	Notes
<session-id>	string	Optional · Reads from cli

Example

you session resume
you session resume session-beta
you session resume dur-sess-js-run-n-001
you --json session resume session-beta

you session show

#you-session-show

Show one live factory session

Show one live factory session from GET /factory-sessions/{session_id}. Human output uses FactorySession as the canonical runtime noun and prints orchestrator kind plus Petri or JavaScript runtime projections. Dynamic workflow wording appears only as JavaScript shorthand. Omit session-id to target the default compatibility session (~default). Use global --json for the API-shaped FactorySession payload and global --server to target the same factory API base URI as work list and factory query.

Arguments

Argument	Type	Notes
<session-id>	string	Optional · Reads from cli

Example

you session show
you session show session-beta
you --json session show session-beta

you submit

#you-submit

Submit work to a running factory

Submit work to a running you-agent-factory service. Unary submit (this command) posts one work item with --name, --work-type-name, and --payload. For multi-work FACTORY_REQUEST_BATCH ingress to an already-running session, use you submit batch. See you submit batch --help and you docs batch-inputs. By default unary submit targets the default compatibility session. Use --session to submit to one specific live factory session instead.

Flags

Flag	Type	Description
--namerequired	string	authored request name for the submitted work (required)
--payloadrequired	string	path to payload file (.json or .md) (required)
--session	string	target one live factory session; omit to use the default compatibility session
--work-type-namerequired	string	work type name to submit to (required)

Example

you submit

you submit batch

#you-submit-batch

Upsert a FACTORY_REQUEST_BATCH to a running factory

Upsert canonical FACTORY_REQUEST_BATCH JSON to a running you-agent-factory session. The document must use type FACTORY_REQUEST_BATCH with at least one works entry. See you docs batch-inputs for the batch schema, relation rules, and examples. Batch input modes (first match wins): --file <path> read batch JSON from path; use --file - to read stdin <path> read batch JSON from an existing filesystem path (primary form) - read batch JSON from stdin <inline-json> positional whose first non-whitespace byte is { is parsed as JSON (no args) when stdin is not a TTY, read the full piped document from stdin When both --file and a positional path are provided, --file wins. When a file path or --file is set, stdin is ignored. Inline JSON is convenient for small batches; shell argument length limits apply—use a file or pipe for large documents. Use --dry-run to parse and validate locally, print a summary, and perform no HTTP. Valid --dry-run exits 0 even when the factory is unreachable. By default the command targets the default compatibility session (~default). Use --session to upsert into one specific live factory session instead. Global flags (place before the subcommand): --server selects the factory API base URI; --json emits structured success output on stdout; --verbose and --debug emit concise request metadata on stderr without logging batch payload content.

Arguments

Argument	Type	Notes
<input>	string	Optional · Reads from cli, stdin

Flags

Flag	Type	Description
--dry-run	bool	validate input and print a summary without sending HTTP
--file	string	read batch JSON from path; use - to read stdin (wins over a positional path)
--session	string	target one live factory session; omit to use the default compatibility session

Example

# Upsert a batch file to the default session.
you submit batch ./factory/inputs/BATCH/my-batch.json

# Explicit file flag (wins over a positional path when both are set).
you submit batch --file ./batches/deploy.json

# Pipe batch JSON without a temp file.
cat batch.json | you submit batch

# Read batch JSON from stdin explicitly.
you submit batch - < batch.json

# Validate locally without contacting the server.
you submit batch --dry-run ./batch.json

# Target a non-default live session with structured output.
you --server http://localhost:9090 --json submit batch --session session-beta ./batch.json

you work

#you-work

Inspect work from a running factory

Inspect and control work on a running you-agent-factory service. Subcommands: list list work from GET /factory-sessions/{session_id}/work with optional filters and pagination show show one work item from GET /factory-sessions/{session_id}/work/{work_id} move move one work item to another authored state through POST /factory-sessions/{session_id}/work/{work_id}/move visualize read a local FACTORY_REQUEST_BATCH JSON file and render its dependency graph to stdout API-backed list, show, and move commands target the default compatibility session unless --session is set. Use global --json to emit API-shaped responses on stdout; diagnostics stay on stderr when --verbose or --debug is set.

Example

you work list
you work show work-123
you work visualize batch.json

you work list

#you-work-list

List work from a running factory

List work from a running you-agent-factory service. By default the command targets the default compatibility session. Use --session to route the request to one specific live factory session instead. Run you session list to discover live session ids. Optional filters are applied on the server before pagination. --name matches a case-insensitive substring of the work name. --work-type-name matches workTypeName exactly. --trace-id matches traceId or currentChainingTraceId exactly. Combine filters with --max-results and --next-token to page through the filtered result set.

Flags

Flag	Type	Default	Description
--max-results	int	0	maximum work items to return per page after server-side filters
--name	string	—	filter by case-insensitive substring of work name (applied before pagination)
--next-token	string	—	pagination cursor returned by a previous work list response
--session	string	—	target one live factory session; omit to use the default compatibility session
--sort-by	string	—	sort returned work by field (state.type)
--state-name	string	—	filter by current state name
--state-type	string	—	filter by current state type (INITIAL, PROCESSING, TERMINAL, FAILED)
--trace-id	string	—	filter by exact traceId or currentChainingTraceId (applied before pagination)
--work-type-name	string	—	filter by exact workTypeName (applied before pagination)

Example

you work list
you work list --session session-beta --json

you work move

#you-work-move

Move one work item to another authored state

Move one work item to another authored marking state on a running you-agent-factory service. By default the command targets the default compatibility session. Use --session to route the request to one specific live factory session instead. Run you session list to discover live session ids. Moves are rejected while the work item is in an active dispatch. Repeating the same --request-id after a successful move returns 409 without a second mutation.

Arguments

Argument	Type	Notes
<work-id>	string	Required · Reads from cli
<state-name>	string	Required · Reads from cli

Flags

Flag	Type	Description
--request-id	string	optional client idempotency key for operator moves
--session	string	target one live factory session; omit to use the default compatibility session

Example

you work move work-123 ready
you work move work-123 ready --request-id op-1

you work show

#you-work-show

Show one work item from a running factory

Show one work item from a running you-agent-factory service. By default the command targets the default compatibility session. Use --session to route the request to one specific live factory session instead. Run you session list to discover live session ids. After submit, use you work list --name <name> to find work ids, then you work show <work-id> to verify one item without JSON pagination.

Arguments

Argument	Type	Notes
<work-id>	string	Required · Reads from cli

Flags

Flag	Type	Description
--session	string	target one live factory session; omit to use the default compatibility session

Example

you work show work-123
you --json work show work-123

you work visualize

#you-work-visualize

Render a work batch dependency graph as Mermaid

Read a local FACTORY_REQUEST_BATCH JSON file from disk and render its declared work dependencies as a diagram. The required <batch-file.json> argument is a path to any readable batch file. Graph nodes represent work items; directed edges represent declared dependency relations from the batch. Output format (default: mermaid): mermaid Raw Mermaid flowchart syntax written to stdout. markdown-mermaid Markdown with a title and one fenced mermaid code block. This command is read-only. It does not submit work, contact a running factory, or render diagram images. Redirect stdout to save output, for example: you work visualize batch.json > my-graph.mermaid you work visualize --format markdown-mermaid batch.json > graph.md

Arguments

Argument	Type	Notes
<batch-file.json>	string	Required · Reads from cli

Flags

Flag	Type	Default	Description
--format	string	mermaid	output format: mermaid or markdown-mermaid

Example

you work visualize batch.json
you work visualize --format markdown-mermaid batch.json

you workers

#you-workers

Manage worker execution integrations

Inspect and configure customer-facing worker execution integrations.

Example

you workers list

you workers acp

#you-workers-acp

Manage ACP provider integrations

Add or delete operator-configured Agent Client Protocol providers. Use `you workers list` to inspect all providers.

Example

you workers acp add --name cursor-acp --transport stdio --argument 'cursor-agent acp'

you workers acp add

#you-workers-acp-add

Add an ACP provider

Add or replace one operator-configured stdio ACP provider integration.

Flags

Flag	Type	Default	Description
--argumentrequired	string	—	—
--namerequired	string	—	—
--transport	string	stdio	—

Example

you workers acp add --name cursor-acp --transport stdio --argument 'cursor-agent acp'

you workers acp delete

#you-workers-acp-delete

Delete an ACP provider

Delete one operator-configured ACP provider integration without removing built-in provider metadata.

Flags

Flag	Type	Description
--namerequired	string	—

Example

you workers acp delete --name cursor-acp

you workers list

#you-workers-list

List worker integrations

List all selectable built-in and operator-configured worker integrations.

Example

you workers list

46 published CLI commands from the package contract.