Global options and output

These options work on every yofix command. The same page documents the machine-readable output contract that scripts and agents depend on.

Global flags

Flag	Description
--json	Emit a machine-readable JSON envelope on stdout (see below)
--cwd <dir>	Run as if from a different working directory
--team <slug>	Override the active team for this command
--project <slug>	Override the linked project slug
--token <token>	Use this bearer token instead of stored credentials
-y, --yes	Skip confirmation prompts (assume yes)
--no-input	Fail instead of prompting when input is required
--no-color	Disable ANSI color codes
--debug	Show stack traces and verbose error context
--host <url>	Override the API host (default https://app.yofix.ai)
--version	Print the CLI version
--help	Show help for the CLI or a command

Environment variables

Variable	Effect
YOFIX_TOKEN	Bearer token used when no --token is passed. Primary auth method in CI.
YOFIX_HOST	API host to use when --host is not passed (default https://app.yofix.ai).
NO_COLOR	Standard convention; disables colored output, same as --no-color.

Files

Path	Contents
~/.yofix/config.json	Global config and credential fallback (mode 0600)
~/.yofix/cache/	Cached metadata
.yofix/project.json	Per-project link, discovered by walking up from the working directory

JSON envelope

Pass --json and every command prints one of two stable shapes. The schema is a public contract: existing fields never change shape, only new optional fields are added.

A success looks like:

{
  "ok": true,
  "command": "deploy",
  "version": "0.1.6",
  "data": { "deploymentId": "dpl_123", "status": "ready", "previewUrl": "https://..." },
  "warnings": [],
  "elapsedMs": 41280
}

A failure looks like:

{
  "ok": false,
  "command": "deploy",
  "version": "0.1.6",
  "error": {
    "code": "YF_DEPLOY_BUILD_FAILED",
    "message": "Deploy dpl_123 finished with status: failed.",
    "hint": "Run `yofix logs dpl_123` to see why.",
    "docsUrl": "https://yofix.ai/docs/cli/errors#yf_deploy_build_failed"
  },
  "exitCode": 10,
  "elapsedMs": 38110
}

All human-readable progress goes to stderr, so stdout stays clean for piping into jq or an agent even without --json.

Exit codes

CI scripts can switch on the numeric exit code without parsing output.

Code	Meaning	Error code
0	Success	YF_OK
2	Bad usage or missing input	YF_USAGE, YF_MISSING_INPUT
3	Network failure reaching the API	YF_NETWORK
4	Authentication required or expired	YF_AUTH_REQUIRED, YF_AUTH_EXPIRED
5	Resource already exists	YF_CONFLICT
6	Resource not found	YF_NOT_FOUND
7	Plan limit reached	YF_QUOTA_EXCEEDED
8	Server error or timeout	YF_SERVER, YF_TIMEOUT
9	Feature not yet available	YF_NOT_IMPLEMENTED
10	Build finished with a non-zero status	YF_DEPLOY_BUILD_FAILED
11	Directory is not linked to a project	YF_PROJECT_NOT_LINKED
130	Interrupted (Ctrl-C)	YF_INTERRUPTED

Error codes

Every failure carries a stable YF_* code so you can branch on the cause without string-matching the message. Each code, what causes it, and how to fix it has its own section in the Error reference. Failures also include a docsUrl that deep-links straight to the matching section.

Next

• Error reference: every YF_* code, with causes and fixes.
• Agents, JSON and MCP: drive the CLI from scripts and AI agents.
• Use the CLI in CI: branch on exit codes in a pipeline.