Skip to content

CLI for agents

The Cognitive3D CLI is built to be driven by an AI coding agent, a script, or a CI pipeline as well as by a person. It writes structured JSON to stdout by default, reports problems as JSON on stderr, and uses a small set of exit codes, so a program can act on the result without parsing prose.

For installation and every command and flag, see the CLI reference.

Authenticate without a browser

Browser login (cognitive3d auth login) needs a person at a browser. An agent, script, or CI job authenticates with an organization API key instead. The key starts with orgkey-. Developer API keys are not supported.

Set the organization API key and your organization ID as environment variables:

export C3D_API_KEY="orgkey-..."
export C3D_ORG_ID="YOUR_ORG_ID"

You can also store them in ~/.cognitive3d/config.yaml or pass --api-key and --org-id on each command. The CLI uses the first credentials it finds in this order: command-line flags, environment variables, a stored session from auth login, then the config file. See Configuration for the config file format.

On your own machine, an agent can also reuse the session you create with cognitive3d auth login. cognitive3d auth login --email prompts for a password, so it cannot run in a pipeline or any other context without an interactive terminal.

Check the setup first

Run cognitive3d version before anything else. It makes no network call and prints the environment and API endpoint the CLI resolved from your configuration:

cognitive3d version

cognitive3d auth info then shows whether a stored session exists and which organizations it can reach.

Read stdout as data

JSON is the default format, so you do not need --format json. Pipe the output straight to jq:

cognitive3d projects list | jq -r '.[].id'

An empty result is still valid output: [] or {} in JSON, or a header row in CSV. Use --format csv when you want a file that loads into a spreadsheet or a data frame.

Read stderr as messages

stdout carries only the result. Everything else goes to stderr as one JSON object per line, identified by its first key:

Key Meaning
error The command failed. The exit code is not 0.
warning The result on stdout is valid but incomplete or filtered.
info Context, such as why a result is empty.
hint Guidance about the record before it. It is not a second error.

Do not discard stderr. For example, when more sessions match than fit on one page, sessions list and sessions search exit 0 and write a warning:

{"warning":"results_truncated","message":"Showing the 1000 most recent of 1538 sessions in this scene version. To see the rest, continue with --page 1 or raise --limit (max 1000)."}

The device filters --device-category and --runtime-host also write a warning, because they exclude sessions recorded before device classification ran. If you save stdout only, you lose the record that the figure is partial.

Branch on the exit code

Check the exit code, not the size of the output, to tell success from failure:

Code Meaning
0 Success, including a query that matched no data.
1 General error, such as a network failure.
2 Authentication error. A project ID that does not exist or is not yours also exits 2.
3 Not found. sessions search exits 3 when no sessions match.
4 Validation error, such as a bad flag, a missing required flag, or an unreadable config file.

Invalid flags and an unsupported --format fail with exit code 4 before any network request, so a typo costs no API call. See Exit codes for the edge cases.

See also

intercom If you have a question or any feedback about our documentation please use the Intercom button (purple circle) in the lower right corner of any web page or join our Discord.