What the CLI tool is for

The Cognitive3D CLI is a command-line interface for the Cognitive3D spatial analytics API. It gives you programmatic, scriptable access to your organization's VR, AR, and XR analytics data — without needing the web dashboard.

Who it's for:

• Data scientists who want to pull session and performance data into their own analysis pipelines.
• IT admins managing deployments across multiple projects and environments.
• CI/CD pipelines that need to gate deployments on performance or objective pass rates.
• AI agents and automation — the default JSON output is structured for machine consumption.

Key capabilities:

• Query organization summaries, project details, session data, participants, objectives, ExitPoll surveys, and eight KPI scores covering performance, comfort, and spatial analytics.
• Three output formats: JSON (default), table, and CSV.
• Cross-platform: macOS, Linux, and Windows.
• Predictable exit codes and structured error output for reliable scripting.

---

Installation

Homebrew (macOS and Linux)

The fastest way to install on macOS or Linux. The CLI ships as a Homebrew cask from the CognitiveVR tap:

brew install cognitivevr/tap/cognitive3d

To upgrade later:

brew update && brew upgrade --cask cognitive3d

Archive download (all platforms)

Every release publishes a compressed archive per platform on the Releases page — not a bare binary. Each archive contains the cognitive3d executable plus LICENSE, README.md, config.yaml.example, and .env.example.

Platform	Archive name
macOS (Apple Silicon)	cognitive3d_<version>_Darwin_arm64.tar.gz
macOS (Intel)	cognitive3d_<version>_Darwin_x86_64.tar.gz
Linux (x86_64)	cognitive3d_<version>_Linux_x86_64.tar.gz
Linux (ARM64)	cognitive3d_<version>_Linux_arm64.tar.gz
Windows (x86_64)	cognitive3d_<version>_Windows_x86_64.zip
Windows (ARM64)	cognitive3d_<version>_Windows_arm64.zip

Extract the archive, then move the executable to a directory on your PATH:

tar -xzf cognitive3d_1.0.0_Darwin_arm64.tar.gz
sudo mv cognitive3d /usr/local/bin/

Each release also publishes cognitive3d_<version>_checksums.txt (SHA-256) so you can verify a download:

shasum -a 256 -c cognitive3d_1.0.0_checksums.txt --ignore-missing

Windows

1. Download cognitive3d_<version>_Windows_x86_64.zip from the Releases page, or the arm64 zip on ARM hardware.
2. Extract it — the archive contains cognitive3d.exe.
3. Move cognitive3d.exe to a folder that is in your system PATH (for example, C:\Tools\).
4. Or add the folder containing the .exe to your PATH environment variable.

---

Configuration

Browser login (recommended)

The easiest way to authenticate is with browser-based login — the same Google or Microsoft SSO you use for the Cognitive3D dashboard:

cognitive3d auth login

This opens a browser page where you choose Google SSO, Microsoft SSO, or email and password. After you authenticate, the CLI stores your session in ~/.cognitive3d/tokens.json (permissions 0600) and uses it for every subsequent command. If your account has access to a single organization, the org ID is set automatically.

You can skip the chooser page and go straight to one method:

cognitive3d auth login --google      # Google SSO in the browser
cognitive3d auth login --microsoft   # Microsoft SSO in the browser
cognitive3d auth login --email       # email and password, prompted in the terminal

To log in to the development environment instead:

cognitive3d auth login --env development

The environment name must be spelled out in full — production or development. Abbreviations such as dev are rejected with exit code 4.

Note

Firewalls and remote shells: browser login completes over a loopback callback on port 11437. If that port is occupied or blocked, or you are on a machine with no browser, use cognitive3d auth login --email or an organization API key instead.

Organization API key authentication (CI/CD and scripts)

For CI/CD pipelines, scripts, and headless environments, use an organization API key instead.

The CLI needs two pieces of information to authenticate: your organization API key and your organization ID.

Warning

Important: This CLI requires an organization API key, which starts with orgkey-. Developer API keys are not supported. You can find your organization API key in the Cognitive3D dashboard under Organization Settings → API Keys.

There are three ways to provide API key credentials. The precedence order is command-line flags, then environment variables, then a stored session from auth login, then the config file.

Option 1: environment variables

The simplest approach — set these in your shell profile or CI/CD environment:

export C3D_API_KEY="orgkey-abc123..."
export C3D_ORG_ID="272"

Optionally set the environment, which defaults to production:

export C3D_ENV="production"

Option 2: configuration file

For managing multiple environments, create ~/.cognitive3d/config.yaml:

default_environment: production

environments:
  production:
    api_base_url: https://api.cognitive3d.com
    data_base_url: https://data.cognitive3d.com
    api_key: orgkey-your-production-key-here
    org_id: "272"
    # https_proxy: http://proxy.corp.example.com:8080
  development:
    api_base_url: https://api.c3ddev.com
    data_base_url: https://data.c3ddev.com
    api_key: orgkey-your-development-key-here
    org_id: "76"

Switch between the blocks with --env or C3D_ENV. To keep the config somewhere else, pass --config /path/to/config.yaml.

Warning

A config file that cannot be read or parsed is a hard failure with exit code 4. That includes a malformed YAML file at the default location, a --config path that does not exist, and an unrecognized C3D_ENV value. The CLI reports the error rather than silently falling back to defaults, so a typo in CI fails loudly instead of querying the wrong environment.

Option 3: command-line flags

Pass credentials directly, which is useful for one-off commands or testing:

cognitive3d --api-key "orgkey-abc123..." --org-id "272" org summary

Corporate proxy

If you're behind a corporate proxy, add https_proxy to the relevant environment block in your config file:

environments:
  production:
    api_base_url: https://api.cognitive3d.com
    api_key: orgkey-...
    org_id: "272"
    https_proxy: http://proxy.corp.example.com:8080

Proxy precedence: the HTTPS_PROXY and HTTP_PROXY environment variables override the config file setting. Use NO_PROXY=* to bypass all proxies.

---

Starter commands

Once you're configured, work through these in order — each one confirms something the next depends on. Replace 643 with one of your own project IDs.

1. Verify your installation

This command reaches no network:

cognitive3d version

It prints the CLI version and commit, the build date, the Go runtime, and — most usefully — the environment and API endpoint it resolved from your configuration:

{
  "version": "v1.0.0",
  "commit": "5e1ab14",
  "built": "2026-08-20T00:00:00Z",
  "go_version": "go1.26.6",
  "environment": "production",
  "api_base": "https://api.cognitive3d.com"
}

If environment or api_base is not what you expect, fix that before running anything else — every other command inherits it.

2. Confirm who you are

Check the identity behind your stored session:

cognitive3d auth info

This shows whether you are logged in, which account and user ID the session belongs to, which environment it is valid for, and the organizations you can reach. It is the fastest way to tell an authentication problem from a data problem.

3. Get your organization overview

Start with the organization-wide numbers:

cognitive3d org summary --format table

This shows your organization name and status, total projects, total sessions, total scenes, average session duration, and the most recent activity timestamp.

4. List all projects

Find the project IDs the rest of the commands need:

cognitive3d projects list --format table

This returns every project in your organization with its ID, name, type (for example vr), session count, scene count, and average session duration.

5. Drill into a specific project

Inspect one project's structure:

cognitive3d projects get 643 --format table

This shows project metadata plus every scene, its scene versions, and their session statistics. You need a scene ID and a version from here before you can call sessions list.

6. Read a headline KPI

Get one number for the project's health over the last 30 days:

cognitive3d score app_performance --project 643 --format table

Swap app_performance for any of the eight score types — cyberwellness, ergonomics, fps, and the rest are listed under Score.

7. Find sessions by participant

Search for a specific participant's sessions:

cognitive3d sessions search --project 643 --participant "john" --format table

This searches by participant name or ID, matching on substrings. Use --project all to search across every project in your organization at once.

Note

If a command returns no rows, that is usually a filter, not an outage. Test and editor sessions, and sessions with no gaze data, are excluded by default. Add --include-test and --include-junk to see them. Date filters default to the last 30 days on most commands — widen the window with --days 365.

---

Output formats

Every command supports three output formats via the --format flag. The CLI validates --format before any network call, so a typo costs you an immediate exit 4 rather than a wasted API round trip.

An empty result is still valid output, never an empty stream: an empty JSON collection renders as [] or {}, and CSV emits its header row. A command that finds no data exits 0, so a script can distinguish "no sessions matched" from a real failure by the exit code rather than by parsing.

JSON (default)

Structured JSON goes to stdout — ideal for piping to jq, feeding into scripts, or consuming from AI agents:

cognitive3d projects list | jq '.[] | select(.sessions > 100)'

Table

Human-readable tabular output reads well in a terminal:

cognitive3d projects list --format table

CSV

Comma-separated values import into Excel, Google Sheets, or data analysis tools:

cognitive3d projects list --format csv > projects.csv

Same command, three formats

Here's how the same command looks in each format:

# Machine-readable JSON (pipe to jq, scripts, etc.)
cognitive3d org summary

# Human-readable table
cognitive3d org summary --format table

# Spreadsheet-ready CSV
cognitive3d org summary --format csv

---

Command reference

Below is the full set of commands organized by group. All commands support --format json|table|csv, and JSON is the default.

Shared session filters. Commands that query session data accept a common set of filters. Defaults differ per command, so check the flags line on each entry.

• Date range — use --days to look back a number of days (maximum 365) or --from and --to for an explicit range. The two styles are mutually exclusive, and --to requires --from. Dates accept Unix milliseconds, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ssZ. The --days default is 30 on most commands, but 90 on sessions list, objectives results, and exitpolls counts.
• Session quality — --include-test, aliased as --include-editor, adds test and editor sessions. --include-junk adds sessions with no gaze data. Both are excluded by default, matching the dashboard.
• Multiple projects — where a command's --project documents it, you may pass a single ID, a comma-separated list, or all to sweep every project in the organization.
• Device filters — --device-category and --runtime-host narrow results to specific hardware and runtimes. Both take a comma-separated list. --device-category accepts console, desktop, emulator, glasses, hmd, mobile, tablet, and unknown. --runtime-host accepts editor, native_desktop, native_mobile, native_standalone, native_tethered, unknown, web_browser, and webxr.

Warning

Device filters narrow your session pool. They match on the canonical c3d.device.derived.* fields, which only exist on sessions the device-classification backfill has reached. Sessions recorded before classification ran are excluded, so a filtered figure covers device-classified sessions only — the CLI writes a warning to stderr whenever you use either flag. Coverage grows as the backfill progresses. Every value listed above is accepted even if no device resolves to it today; such a filter returns no sessions rather than an error.

Organization

org summary

Get a high-level overview of your organization: name and status, total projects, total sessions, total scenes, average session duration, and the latest activity timestamp.

cognitive3d org summary --format table

Flags: none beyond the global flags.

org trends

Get monthly session counts across the organization, with growth rates, peak activity periods, and an overall trend summary.

The window is the current UTC calendar month plus the 11 complete months before it, summed across every project. Because the current month is still partial, its growth rate reports N/A rather than a misleading figure. Test and junk sessions are excluded, matching org summary.

cognitive3d org trends --format table

Flags: none beyond the global flags.

Projects

projects list

List all projects in your organization with their ID, name, type, session count, scene count, and average session duration. Use it to find the project IDs the other commands need.

cognitive3d projects list --format table

Flags: none beyond the global flags.

projects get <id>

Get detailed information about a specific project including scenes, scene versions, and session statistics. Use it to find the scene ID and version that sessions list requires.

cognitive3d projects get 643 --format table

A mistyped or inaccessible project ID exits 2, not 3 — the API answers 403 for a project that either does not exist or is not yours, and does not distinguish the two.

Note

Known limitation: the session_count_by_month field is always returned as an empty array, because the upstream organization endpoint no longer supplies it. For monthly counts, use org trends.

projects compare <id> <id> [id...]

Compare 2–5 projects side by side on sessions, scenes, total time, duration, and engagement. If some of the requested projects cannot be read, the comparison still returns the ones that succeeded.

cognitive3d projects compare 643 645 721 --format table

Flags: none beyond the global flags. Project IDs are positional arguments, not --project values.

projects session-times

Get the average session time in minutes and a histogram of session durations, bucketed in five-minute bands up to an hour plus a 60plus bucket. This helps you understand participant engagement patterns and how session length is distributed.

cognitive3d projects session-times --project 643 --format table
cognitive3d projects session-times --project 643,645 --days 90
cognitive3d projects session-times --project all --format csv > session-times.csv

Flags: --project (required; ID, comma-separated IDs, or all), --days (default 30, maximum 365), --from, --to, --include-test or --include-editor, --include-junk, --device-category, --runtime-host.

projects sdk-versions

Get the Cognitive3D analytics SDK versions used across sessions. This shows each SDK version string and how many sessions used it — useful for tracking SDK adoption and finding builds still shipping an outdated version.

cognitive3d projects sdk-versions --project 643 --format table
cognitive3d projects sdk-versions --project all --days 365
cognitive3d projects sdk-versions --project 643 --format csv > sdk-versions.csv

Flags: --project (required; ID, comma-separated IDs, or all), --days (default 30, maximum 365), --from, --to, --include-test or --include-editor, --include-junk, --device-category, --runtime-host.

projects device-info

Get the device breakdown for a project's sessions, as a session count per distinct value in each category.

Two kinds of category are returned. The canonical classification, derived from the c3d.device.derived.* fields and consistent with the Cognitive3D MCP server and the dashboard, covers Device Category, Device Family, Device Model Family, Device Model, and Device Runtime Host. The raw hardware reports sent by the SDK cover Device CPU, Device CPU Vendor, Device GPU, Device GPU Vendor, Device Operating System, Device Memory Size (GB), and the enabled-feature flags Device Controller Inputs Enabled and Device Eye Tracking Enabled.

The canonical values are the same vocabulary that --device-category and --runtime-host filter on, so this command is the natural way to discover which filter values your data actually contains.

cognitive3d projects device-info --project 643 --format table
cognitive3d projects device-info --project 643,645 --days 90
cognitive3d projects device-info --project all --format csv > device-info.csv

Flags: --project (required; ID, comma-separated IDs, or all), --days (default 30, maximum 365), --from, --to, --include-test or --include-editor, --include-junk, --device-category, --runtime-host.

projects demographics

Get participant demographic data: playable space sizes and dimensions (for example, 2.0 x 1.6 meters), average playable space, geographic distribution by country with average session durations, and a regional breakdown by subdivision (for example, CA-BC or US-OR).

cognitive3d projects demographics --project 643 --format table
cognitive3d projects demographics --project all --days 365
cognitive3d projects demographics --project 643 --format csv > demographics.csv

Flags: --project (required; ID, comma-separated IDs, or all), --days (default 30, maximum 365), --from, --to, --include-test or --include-editor, --include-junk, --device-category, --runtime-host.

projects head-orientation

Get HMD head orientation histogram data showing how participants orient themselves in physical versus virtual space. This returns counts and percentages for yaw angle bins, in 10-degree steps from -180° to 180°. 0° is forward-facing, positive values are right, and negative values are left.

cognitive3d projects head-orientation --project 643 --format table
cognitive3d projects head-orientation --project 643,645
cognitive3d projects head-orientation --project all --format csv

Flags: --project (required; ID, comma-separated IDs, or all), --days (default 30, maximum 365), --from, --to, --include-test or --include-editor, --include-junk, --device-category, --runtime-host.

projects scene-durations

Get the average time participants spend in each scene within a project. This shows per-scene average session durations in HH:MM:SS format, so you can see which scenes hold attention and which are passed through.

cognitive3d projects scene-durations --project 643 --format table
cognitive3d projects scene-durations --project all --days 365
cognitive3d projects scene-durations --project 643 --format csv > scene-durations.csv

Flags: --project (required; ID, comma-separated IDs, or all), --days (default 30, maximum 365), --from, --to, --include-test or --include-editor, --include-junk, --device-category, --runtime-host.

Users

users list

Get a paginated list of the participants and devices that have recorded sessions in a project. This supports substring and wildcard matching across participant ID, participant name, and device ID.

cognitive3d users list --project 643 --format table
cognitive3d users list --project 643 --search "john"
cognitive3d users list --project 643 --type participant --order-by lastSeen
cognitive3d users list --project 643 --type device --sort asc --order-by firstSeen
cognitive3d users list --project 643 --limit 100 --page 1

Flags: --project (required), --search, --type (participant, device, or a comma-separated combination; defaults to both), --sort (asc or desc, default desc), --order-by (id, sessionCount, lastSeen, or firstSeen; default sessionCount), --limit (default 10, maximum 1000), --page (zero-indexed), --days (default 30), --from, --to, --include-test.

The default --limit of 10 is small — raise it before concluding a participant is absent.

Sessions

sessions list

List sessions for a project, scene, and version. This returns session metadata, timestamps, durations, and participant information. Exactly one version selector is required: --version-id, --version-num, or --version-latest.

cognitive3d sessions list --project 643 --scene d787e3b9-... --version-id 1857 --format table
cognitive3d sessions list --project 643 --scene d787e3b9-... --version-num 1
cognitive3d sessions list --project 643 --scene d787e3b9-... --version-latest
cognitive3d sessions list --project 643 --scene d787e3b9-... --version-latest --days 30 --format csv > sessions.csv

Flags: --project (required), --scene (required, a scene UUID), exactly one of --version-id, --version-num, or --version-latest (required), --days (default 90, maximum 365), --from, --to, --limit (default 1000, maximum 1000), --page (zero-indexed), --device-category, --runtime-host.

Note that the --days default here is 90, not the 30 used by most commands. Omitting all three version selectors exits 4.

sessions search

Search sessions by participant name or ID, matching on substrings. Use --project all to search across your entire organization.

cognitive3d sessions search --project 643 --participant "john" --format table
cognitive3d sessions search --project all --participant "device-42"
cognitive3d sessions search --project 643 --participant "john" --include-test
cognitive3d sessions search --project 643 --participant "john" --limit 50 --page 1

Flags: --project (required; ID, comma-separated IDs, or all), --participant (required), --days (default 30, maximum 365), --from, --to, --limit (default 20, maximum 1000), --page (zero-indexed; requires a single --project), --include-test.

Objectives

objectives list

List all objective configurations, meaning the definitions, for a project.

cognitive3d objectives list --project 643 --format table

objectives count

Get a quick count of the objectives defined in a project, with an active and inactive breakdown.

cognitive3d objectives count --project 643

objectives analyze

Analyze objective complexity, component types, and event patterns across a project's objectives.

cognitive3d objectives analyze --project 643 --format table

objectives results

Get objective success and failure results with calculated metrics over the date range. Results are correlated back to their objective definitions, so each row carries the objective's name and description rather than a bare version ID.

cognitive3d objectives results --project 643 --days 90 --format table

Flags: objectives list, count, and analyze take only --project (required) — they read configuration rather than session data, so date and session filters do not apply. objectives results takes --project (required), --days (default 90, maximum 365), --from, --to, --include-test or --include-editor, and --include-junk.

Score

One command returns one KPI, chosen by score_type. This is the canonical home for every performance and spatial-analytics metric — it replaces the former performance and spatial subcommand groups. The score_type vocabulary is shared with the Cognitive3D MCP server's get_score tool, so the same name means the same metric in both.

score <score_type>

Call the command with a score type and a project:

cognitive3d score <score_type> --project <id>[,<id>,...|all]

score_type	What it returns
app_performance	App performance score (0–100 aggregate performance).
performance_standards	Percentage of session time above the 72 Hz and 60 Hz VR thresholds.
fps	Average frame rate, in Hz.
cyberwellness	Cyberwellness score (0–100, where higher means lower cybersickness risk), with component scores and a prior-period trend.
sit_stand	Standing, sitting, and mixed posture percentages.
ergonomics	Ergonomics score (0–100) with comfort and reach or strain sub-scores.
hand_controller	Hands versus controllers versus neither, as input percentages.
ergo_duration_correlation	Correlation between ergonomics score and session duration.

Hyphenated forms are accepted as well — sit-stand is equivalent to sit_stand. An unrecognized score_type exits 4 and lists the valid values.

cognitive3d score app_performance --project 643 --format table
cognitive3d score fps --project 643,645,721
cognitive3d score cyberwellness --project all --days 365 --format table
cognitive3d score ergonomics --project 643,645 --from 2026-01-01 --to 2026-06-30
cognitive3d score sit_stand --project 643 --device-category hmd
cognitive3d score ergo_duration_correlation --project 643 --format csv > ergo.csv

Flags: --project (required; ID, comma-separated IDs, or all), --days (default 30, maximum 365), --from, --to, --include-test or --include-editor, --include-junk, --device-category, --runtime-host.

Warning

Cyberwellness halves your window. It is a trend metric, matching the dashboard widget: the reported score covers the most recent half of the requested range, and the prior_* fields cover the earlier half. So --days 90 compares the last 45 days against the 45 before them. Every other score type covers the full window.

Interpreting cyberwellness: ≥ 90 Excellent · ≥ 75 Good · ≥ 50 Fair · < 50 Needs Improvement. Component scores, each 0–100, cover visual continuity, translational movement, acceleration variability, and continuous movement.

Interpreting ergonomics: ≥ 90 Excellent · ≥ 75 Good · ≥ 50 Moderate · < 50 Poor. The composite blends controller ergonomics (horizontal, forward, and vertical reach) with headset orientation strain (pitch and roll), and the sub-scores are returned alongside it.

Interpreting ergo_duration_correlation: this returns a Pearson correlation coefficient, a regression slope, and a plain-language interpretation. It answers whether sessions with better ergonomics tend to run longer, which is the usual proxy for whether comfort drives engagement.

Deprecated aliases

The performance and spatial subcommand groups were consolidated into score. The old commands still work — they are hidden aliases that produce unchanged output on stdout and print a deprecation warning to stderr — so existing scripts keep running. They will be removed in the next major version. Migrate using this mapping:

Deprecated command	Use instead
performance standards	score performance_standards
performance score	score app_performance
performance fps	score fps
spatial cyberwellness	score cyberwellness
spatial sit-stand-percentages	score sit_stand
spatial ergonomics	score ergonomics
spatial hand-controller-score	score hand_controller
spatial ergo-duration	score ergo_duration_correlation

ExitPolls

These commands give read-only access to ExitPoll survey configuration and results. ExitPolls have two entities: question sets, which are versioned and immutable so that editing one creates a new version, and hooks, the named trigger points an application requests questions from. Each hook pins exactly one question-set version.

Write operations, such as creating question sets and assigning hooks, are not available in the CLI. Use the Cognitive3D MCP server or the dashboard for those.

exitpolls list-question-sets

List a project's question-set versions: set name and version number, where name:version is the identifier hooks pin, plus display title, question count, and active or archived status. Archived versions are hidden unless you ask for them.

cognitive3d exitpolls list-question-sets --project 643 --format table
cognitive3d exitpolls list-question-sets --project 643 --archived

Flags: --project (required), --archived.

exitpolls show-question-set

Get the full question definitions for one question set — every question with its type, exact title, scale range and labels, and answer options, per version. This defaults to all versions of the named set.

This is the starting point for editing a survey. Because versions are immutable, changing a question means recreating the set from the complete question list, and response data cannot reconstruct that list: unselected answer options, scale ranges, and labels never appear in responses.

cognitive3d exitpolls show-question-set --project 643 --question-set end_survey
cognitive3d exitpolls show-question-set --project 643 --question-set end_survey --version 2
cognitive3d exitpolls show-question-set --project 643 --question-set old_survey --archived

Flags: --project (required), --question-set (required; see list-question-sets), --version (defaults to all versions), --archived.

exitpolls list-hooks

List a project's hooks: the hook name an application requests, the question-set version assigned to it as name:version or unassigned, the description, and whether it is active.

An application requesting an unassigned hook continues silently rather than erroring, so an unassigned hook is a common reason a survey never appears in a build.

cognitive3d exitpolls list-hooks --project 643 --format table

Flags: --project (required).

exitpolls counts

Get aggregated response counts for one question-set version, joined with question titles and types. Each row is one distinct answer value, or the skipped bucket, for one question.

cognitive3d exitpolls counts --project 643 --question-set end_survey --version 2
cognitive3d exitpolls counts --project 643 --question-set end_survey --version 2 --days 365
cognitive3d exitpolls counts --project 643 --question-set end_survey --version 2 --from 2026-01-01 --to 2026-06-30

Flags: --project (required), --question-set (required), --version (required), --days (default 90, maximum 365), --from, --to, --include-test or --include-editor, --include-junk.

Authentication

auth login

Open a browser to sign in, then store the session locally for subsequent commands. If your account has access to a single organization, the org ID is set automatically. Sign-in completes over a loopback callback on port 11437.

cognitive3d auth login
cognitive3d auth login --google
cognitive3d auth login --microsoft
cognitive3d auth login --email
cognitive3d auth login --env development

Flags: --google (skip straight to Google SSO), --microsoft (skip straight to Microsoft SSO), --email (prompt for email and password in the terminal). These flags are mutually exclusive.

With no flag, the browser opens a chooser page offering the SSO providers and an email-and-password form. --email needs an interactive terminal for the password prompt, so it cannot run in a pipeline or a non-TTY context — use an organization API key there instead.

auth logout

Clear stored authentication credentials, removing ~/.cognitive3d/tokens.json. Credentials supplied by flag or environment variable are unaffected.

cognitive3d auth logout

auth info

Show the current authentication status: login state, account, user ID, the organizations you can reach, and which API environment the session is valid for. A session is environment-specific — logging in to production does not authenticate you against development.

cognitive3d auth info
cognitive3d auth info --format table

Utility

version

Print the CLI version and commit, the build date, the Go runtime, and the environment and API endpoint resolved from your configuration. This makes no network call, so it is a safe first check that configuration is being read as you expect.

cognitive3d version

completion

Generate a shell completion script for bash, zsh, fish, or powershell.

cognitive3d completion zsh > "${fpath[1]}/_cognitive3d"

---

Global flags

These flags are available on every command:

Flag	Environment variable	Description
--api-key	C3D_API_KEY	Organization API key.
--org-id	C3D_ORG_ID	Organization ID.
--env	C3D_ENV	Environment name — production or development, spelled in full.
--config	—	Path to the config file (default ~/.cognitive3d/config.yaml).
--format	—	Output format: json (default), table, or csv.
--verbose	—	Enable debug output to stderr.

---

Exit codes

Code	Meaning
0	Success.
1	General error (network failure, unexpected error).
2	Authentication error (invalid or missing organization API key or org ID).
3	Not found (invalid scene ID, question set, version, and so on).
4	Validation error (bad flag combination, missing required flag, unreadable config).

Two cases are worth knowing before you branch on these in a script:

• A bad project ID exits 2, not 3. The API answers 403 for a project that either does not exist or is not accessible to your key, and does not distinguish the two, so it surfaces as an authorization failure.
• Configuration problems exit 4. An unreadable or malformed config file, a --config path that does not exist, and an unrecognized C3D_ENV value all fail immediately rather than falling back to a default environment.

A command that runs successfully but matches no data exits 0 and still emits well-formed empty output. Check the exit code, not the emptiness of the payload, to tell "no results" from "failed".

---

Note

Tip: Run cognitive3d help or cognitive3d <command> --help for usage details and examples on any command. --help works even when configuration is broken, so it is always available for troubleshooting.

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.