> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Global options

> Flags available on every Youka CLI command

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

## Flags

| Flag                      | Description                                                                                                                                       |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--json`                  | Machine 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`.                                                       |
| `--wait`                  | Poll 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.                                                                                        |
| `--quiet`                 | Suppress non-JSON progress output when combined with `--wait`.                                                                                    |
| `--no-color`              | Disable 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:

```json theme={null}
{
  "ok": true,
  "data": {
    /* command result */
  }
}
```

Failure:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key.",
    "details": null
  }
}
```

Exit codes:

| Code | Meaning                                        |
| ---- | ---------------------------------------------- |
| `0`  | Success.                                       |
| `1`  | Runtime error (network, API, rendering).       |
| `2`  | Invalid input (bad flags, unreadable payload). |

<Tip>
  Pipe the envelope through `jq` for scripting: `youka project show $ID --json |
      jq '.data.state'`.
</Tip>

## 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.

<CodeGroup>
  ```bash from-file theme={null}
  youka preset create --body ./preset.json --json
  ```

  ```bash from-stdin theme={null}
  cat preset.json | youka preset create --body - --json
  ```

  ```bash override-with-flag theme={null}
  # CLI flag takes priority over matching fields from --body
  youka preset create --body ./preset.json --name "Override name" --json
  ```
</CodeGroup>

## 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.

```bash theme={null}
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.

```bash theme={null}
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

| Variable             | Purpose                                          |
| -------------------- | ------------------------------------------------ |
| `YOUKA_API_KEY`      | API key used when not set via `youka login`.     |
| `YOUKA_API_BASE_URL` | Alternative API base URL. Overridden by `--api`. |

## What's next

* [Account](/en/cli/account) - save your API key
* [Projects](/en/cli/projects) - your first scripted workflow
* [AI agents](/en/agents) - operating rules for agent authors