Skip to main content
Every youka command accepts the same set of global flags. They control output mode, input handling, waiting behavior, and the target API.

​
Flags

FlagDescription
--jsonMachine mode: print exactly one JSON envelope to stdout. Logs and progress are suppressed.
--body <file|->Merge a JSON object from a file or stdin. CLI flags override matching fields from --body.
--waitPoll the created resource until it reaches a terminal state. Common on project create, project sync, project separate, and export create.
--idempotency-key <key>Forward an idempotency key to the API on write operations.
--quietSuppress non-JSON progress output when combined with --wait.
--no-colorDisable ANSI color output.
--api <url>Override the API base URL. The /api/v1 suffix is appended automatically when needed.

​
JSON envelope

With --json, the CLI writes exactly one envelope to stdout and nothing else. Success: 
{
  "ok": true,
  "data": {
    /* command result */
  }
}
Failure: 
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key.",
    "details": null
  }
}
Exit codes:
CodeMeaning
0Success.
1Runtime error (network, API, rendering).
2Invalid input (bad flags, unreadable payload).
Pipe the envelope through jq for scripting: youka project show $ID --json | jq '.data.state'.

​
Passing JSON bodies

Any create or update command accepts --body for the full request body. Use it instead of escaping large JSON on the command line. 
youka preset create --body ./preset.json --json

​
Waiting for async jobs

--wait polls the created resource on your behalf and returns the final state. Without --wait, commands return as soon as the job is queued. 
youka project create ./song.mp3 --wait --json
youka export create $ID --wait --download --output ./out.mp4
Pair --wait with --quiet in scripts to suppress the progress bar while still printing the JSON result.

​
Idempotency

Pass --idempotency-key to make write commands safe to retry. Reusing the same key with the same payload returns the original result instead of creating a duplicate. 
youka project create ./song.mp3 \
  --idempotency-key "import-2026-04-08-song-001" \
  --json
Use idempotency keys whenever an agent might retry after a timeout.

​
Environment variables

VariablePurpose
YOUKA_API_KEYAPI key used when not set via youka login.
YOUKA_API_BASE_URLAlternative API base URL. Overridden by --api.

​
What’s next