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, objectives, performance scores, 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:

# One-time setup: add the CognitiveVR tap
brew tap cognitivevr/tap

# Install
brew install cognitive3d

To upgrade later:

brew update && brew upgrade cognitive3d

Binary Download (all platforms)

Download a pre-built binary from the Releases page:

Platform	Binary Name
macOS (Apple Silicon)	`cognitive3d-darwin-arm64`
macOS (Intel)	`cognitive3d-darwin-amd64`
Linux (x86_64)	`cognitive3d-linux-amd64`
Linux (ARM)	`cognitive3d-linux-arm64`
Windows (x86_64)	`cognitive3d-windows-amd64.exe`
Windows (ARM)	`cognitive3d-windows-arm64.exe`

After downloading, make the binary executable (macOS/Linux) and move it to a directory on your PATH:

chmod +x cognitive3d-darwin-arm64
sudo mv cognitive3d-darwin-arm64 /usr/local/bin/cognitive3d

Windows

Download cognitive3d-windows-amd64.exe from the Releases page
Rename it to cognitive3d.exe
Move it to a folder that is in your system PATH (e.g., C:\Tools\)
Or add the folder containing the .exe to your PATH environment variable

Configuration

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 (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 credentials. Precedence order: command-line flags > environment variables > 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 (defaults to production):

export C3D_ENV="production"

Option 2: Configuration File

For managing multiple environments (e.g., production and development), 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

Option 3: Command-Line Flags

Pass credentials directly (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: HTTPS_PROXY / HTTP_PROXY environment variables override the config file setting. Use NO_PROXY=* to bypass all proxies.

Starter Commands

Once you're configured, try these commands to explore your data:

Verify your installation

cognitive3d version

This prints the CLI version, Go runtime, current environment, and API endpoint — confirming everything is wired up correctly.

Get your organization overview

cognitive3d org summary --format table

Shows your organization name, total projects, total sessions, average session duration, and latest activity.

List all projects

cognitive3d projects list --format table

Returns every project in your organization with session counts, scene counts, and average session duration.

Drill into a specific project

cognitive3d projects get 643 --format table

Replace 643 with your project ID. Shows project metadata, all scenes, scene versions, and session statistics.

Find sessions by participant

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

Searches by participant name or ID (substring match). Use --project all to search across every project in your organization.

Output Formats

Every command supports three output formats via the --format flag.

JSON (default)

Structured JSON 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 for quick reading in a terminal:

cognitive3d projects list --format table

CSV

Comma-separated values for importing 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 (JSON is the default). Most commands that query session data support date filtering with --days (default 30), --from, and --to, as well as --include-test and --include-junk flags to include test/editor sessions or sessions with no gaze data.

Organization

`org summary`

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

cognitive3d org summary --format table

`org trends`

Monthly trends analysis showing how your organization's usage is changing over time.

cognitive3d org trends --format table

Projects

`projects list`

List all projects in your organization with session counts, scene counts, and average session duration.

cognitive3d projects list --format table

`projects get <id>`

Get detailed information about a specific project including scenes, scene versions, and session statistics.

cognitive3d projects get 643 --format table

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

Compare 2–5 projects side by side on key metrics.

cognitive3d projects compare 643 645 721 --format table

`projects session-times`

Get the average session time in minutes and a histogram showing the distribution of session durations. Helps understand user engagement patterns and session length distribution.

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, --from, --to, --include-test, --include-junk

`projects sdk-versions`

Get the Cognitive3D analytics SDK versions used across sessions. Shows each SDK version string and how many sessions used it — useful for tracking SDK adoption and identifying outdated versions.

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, --from, --to, --include-test, --include-junk

`projects device-info`

Get device characteristics for sessions in a project. Shows the distribution of device types, models, CPUs, GPUs, operating systems, memory sizes, and enabled features (controller inputs, eye tracking).

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, --from, --to, --include-test, --include-junk

`projects demographics`

Get user demographic data including playable space sizes, geographic distribution by country (with average session durations), and regional breakdown by subdivision (e.g., CA-BC, 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, --from, --to, --include-test, --include-junk

`projects head-orientation`

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

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

Flags: --project (required; ID, comma-separated IDs, or all), --days, --from, --to

`projects scene-durations`

Get the average time participants spend in each scene within a project. Shows per-scene average session durations in HH:MM:SS format, helping you understand which scenes users spend the most and least time in.

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, --from, --to, --include-test, --include-junk

Users

`users list`

Get a paginated list of users (participants and devices) that have recorded sessions in a project. Supports wildcard/substring searching across participant ID, participant name, and device ID.

cognitive3d users list --project 574 --format table
cognitive3d users list --project 574 --search "john"
cognitive3d users list --project 574 --type participant --order-by lastSeen
cognitive3d users list --project 574 --type device --sort asc --order-by firstSeen

Flags: --project (required), --search, --type (participant or device), --sort (asc or desc), --order-by (id, sessionCount, lastSeen, firstSeen), --limit (default 10, max 1000), --page, --days, --from, --to, --include-test

Sessions

`sessions list`

List sessions for a project, scene, and version. Returns session metadata, timestamps, durations, and participant info.

cognitive3d sessions list --project 643 --scene d787e3b9-... --version-id 1857 --format table

Flags: --project (required), --scene (required), --version-id (required), --days, --from, --to

`sessions search`

Search sessions by participant name or ID (substring match). 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"

Flags: --project (required; ID or all), --participant (required), --days, --from, --to

Objectives

`objectives list`

List all objective configurations (definitions) for a project.

cognitive3d objectives list --project 643 --format table

`objectives count`

Get a quick count of objectives defined in a project.

cognitive3d objectives count --project 643

`objectives analyze`

Component analysis of objectives — breaks down objective types and configurations.

cognitive3d objectives analyze --project 643 --format table

`objectives results`

Get success/failure metrics for objectives over the date range.

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

Flags (all objectives commands): --project (required), --days, --from, --to

Performance

`performance standards`

Check what percentage of sessions meet frame rate standards (72 Hz and 60 Hz thresholds).

cognitive3d performance standards --project 643 --format table

`performance score`

Get the app performance score (0–100) for a project based on frame rate and rendering metrics.

cognitive3d performance score --project 643 --format table

Flags (all performance commands): --project (required), --days, --from, --to

Spatial Analytics

`spatial cyberwellness`

Get the composite cyberwellness score estimating susceptibility to cyber sickness. Combines visual continuity and translational movement metrics. Returns both current and prior period scores for trend comparison.

Score interpretation: ≥ 90 Excellent · ≥ 75 Good · ≥ 50 Fair · < 50 Needs Improvement

Component scores (0–100): visual continuity, translational movement, acceleration variability, continuous movement.

cognitive3d spatial cyberwellness --project 643 --format table
cognitive3d spatial cyberwellness --project 643,645 --days 90
cognitive3d spatial cyberwellness --project all --format csv > cyberwellness.csv

Flags: --project (required; ID, comma-separated IDs, or all), --days, --from, --to, --include-test, --include-junk

`spatial sit-stand-percentages`

Get the percentage breakdown of sessions where users were standing, sitting, or in a mixed posture. A lightweight ML algorithm classifies each session based on the standing percentage metric.

cognitive3d spatial sit-stand-percentages --project 643 --format table
cognitive3d spatial sit-stand-percentages --project all --days 365
cognitive3d spatial sit-stand-percentages --project 643 --format csv > posture.csv

Flags: --project (required; ID, comma-separated IDs, or all), --days, --from, --to, --include-test, --include-junk

`spatial ergonomics`

Get the ergonomics score (0–100) measuring how physically comfortable the VR experience is. Returns a composite score blending controller ergonomics (horizontal, forward, and vertical reach) and headset orientation strain (pitch and roll), along with individual sub-scores.

Score interpretation: ≥ 90 Excellent · ≥ 75 Good · ≥ 50 Moderate · < 50 Poor

cognitive3d spatial ergonomics --project 643 --format table
cognitive3d spatial ergonomics --project 643,645 --days 90
cognitive3d spatial ergonomics --project all --format csv > ergonomics.csv

Flags: --project (required; ID, comma-separated IDs, or all), --days, --from, --to, --include-test, --include-junk

`spatial hand-controller-score`

Get the average percentage of users that chose hands, controllers, or neither during sessions. Returns normalized percentages (summing to 100%) for each input type.

cognitive3d spatial hand-controller-score --project 643 --format table
cognitive3d spatial hand-controller-score --project all --days 365
cognitive3d spatial hand-controller-score --project 643 --format csv > input-types.csv

Flags: --project (required; ID, comma-separated IDs, or all), --days, --from, --to, --include-test, --include-junk

Utility

`version`

Print CLI version, Go runtime, current environment, and API endpoint.

cognitive3d version

Global Flags

These flags are available on every command:

Flag	Env 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`)
`--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/missing API key or org ID)
`3`	Not found (invalid project ID, scene ID, etc.)
`4`	Validation error (bad flag combination, missing required flag)

Note

Tip: Run cognitive3d help or cognitive3d <command> --help for usage details and examples on any command.

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.