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:
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.
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.
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.
--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.
Never use --wallet-password <password> or pass an OpenRouter key directly in
a command argument. Use the relevant environment-variable or stdin option.
