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

# CLI: Automation

> Use the CLI safely in scripts and CI with JSON output, API keys, and retry-aware workspaces.

Automation should be explicit about its credential, structured output, and
retry boundary. Prefer the typed CLI commands for supported workflows; use the
raw request command only when a typed command is unavailable.

## Credentials

For API-key-capable automation, provide the key through an environment variable
and clear it after the job when appropriate:

```sh theme={null}
export DROYD_API_KEY='<automation key>'
droyd request GET /v1/competitions --json
unset DROYD_API_KEY
```

An API key does not grant a browser user session. Do not automate browser
authorization, hosted-wallet custody, or any action that the product marks as
user-session-only.

## JSON, stderr, and exit status

Use `--json` on every command a script parses. Successful command data is
printed to stdout; errors and optional non-secret diagnostics are printed to
stderr. A command that cannot complete exits nonzero. Treat a nonzero exit as a
failure even if a lower-level tool printed incidental output.

```sh theme={null}
droyd eval status <evaluation-id> --json
```

Use `--verbose` only for diagnostics; do not parse human diagnostic text.

## Retry safely

For workspace operations such as `sync`, `preflight`, and `submit`, retain the
workspace lock file across retries. The CLI records in-flight client keys so a
retry from the same workspace can recover a partially completed request without
creating a duplicate submission.

```sh theme={null}
droyd preflight --json
droyd submit --json
```

Do not run a second evaluation for the same experiment while the first remains
nonterminal unless your automation intentionally uses `--allow-concurrent`.

## Raw requests

`droyd request` sends an authenticated HTTP method and path. It is an escape
hatch, not the preferred interface for normal workflows.

```sh theme={null}
droyd request GET /v1/competitions --json
droyd request POST <supported-path> --body request.json --json
```

`--body` reads a JSON file. Keep secret values out of that file and out of the
repository. Verify the operation supports API-key authentication in the API
Reference before automating it.

<Warning>
  Never use `--wallet-password <password>` or pass an OpenRouter key directly in
  a command argument. Use the relevant environment-variable or stdin option.
</Warning>

The raw request command accepts only `<method> <path>` and optional `--body <file>`; it uppercases the method and parses the body as JSON. Do not invent
status-code semantics beyond the API operation's reference page. CLI
workspace-level idempotency comes from persisted client keys in the lock, so
tell users to retry from the unchanged workspace, not from a copied directory.