CLI Reference

The Framedash CLI provides terminal access to telemetry data, analytics, and project management. It integrates into CI/CD pipelines for automated map uploads and content syncing.

Installation

npm install -g @framedash/cli

Authentication

Set the API key via an environment variable:

export FRAMEDASH_API_KEY=fd_your_api_key_here

Or pass it explicitly with --api-key:

framedash status --api-key fd_your_api_key_here

Verify your key is valid:

framedash auth

Common Options

Most commands accept these options:

Option	Description
--api-key <key>	API key (or FRAMEDASH_API_KEY env)
--project-id <uuid>	Project ID (or FRAMEDASH_PROJECT_ID env)
--base-url <url>	API host URL (default: https://app.framedash.dev)
--format <fmt>	Output format: json, table, csv (default: json)
-h, --help	Show help

Note

framedash auth does not require --project-id (it verifies the API key only). framedash map-capture uses its own option parser — see below.

Note

--base-url is the application host URL. The CLI appends API paths (e.g. /api/v1/...) internally. This differs from the API overview base URL (api.framedash.dev/api) used for direct REST API calls.

Commands

framedash auth

Verify your API key and show the bound project.

framedash auth

Options: --api-key, --base-url, --format

framedash status

Show project health status.

framedash status

framedash dashboard

Show dashboard KPIs (DAU, MAU, sessions, events).

framedash dashboard --days 30

Option	Values	Default
--days	7, 14, 30, 90	30

Note

The CLI --help text shows 1, 7, 14, 30 but the API validates 7, 14, 30, 90. Using --days 1 returns a 400 error. The values above reflect what the API actually accepts.

framedash retention

Show player retention cohorts (D1, D7, D30).

framedash retention --days 14

Option	Values	Default
--days	7, 14, 30, 90	30

Note

Same CLI help text discrepancy as dashboard above. The API-validated values are 7, 14, 30, 90.

framedash funnel

Analyze event funnels to measure player conversion between steps.

framedash funnel --steps "player.spawn,player.death,player.respawn"

Option	Description	Default
--steps	Comma-separated event names (required, 2-8 steps)	—
--window	Time window in seconds (3600, 21600, 86400, 604800)	86400
--days	Time period (7, 14, 30, 90)	30

framedash query

Execute a SQL query against telemetry data.

# Inline SQL
framedash query "SELECT event_name, count() FROM events GROUP BY event_name"

# From a file
framedash query --file ./queries/daily-active.sql

Option	Description
--file <path>	Read SQL from a file instead of inline argument
--limit <n>	Maximum rows to return

framedash alerts

Manage performance alert rules.

# List all alert rules
framedash alerts list

# Create a new alert rule
framedash alerts create --name "FPS Alert" --map-id <uuid> \
  --threshold-profile-id <uuid> --metric fps

# Update an alert rule
framedash alerts update <alert-id> --name "Updated Alert"

# Deactivate an alert rule
framedash alerts delete <alert-id>

framedash maps

Manage game maps.

# List maps
framedash maps list

# Delete a map by map identifier
framedash maps delete <map-id>

framedash map-capture

Upload captured map images. This command has its own option parser and does not use the shared global options.

# Preview what would be uploaded (dry run)
framedash map-capture --input-dir ./captures --upload --dry-run

# Upload map captures
framedash map-capture --input-dir ./captures --upload \
  --api-key fd_xxx --project-id <uuid>

Option	Description
--input-dir <path>	Directory containing captured map images (required)
--upload	Actually upload the captures (required to perform upload)
--api-key <key>	API key for upload
--project-id <uuid>	Target project
--base-url <url>	API base URL
--dry-run	Preview upload without sending

framedash content

Manage the content registry (items, weapons, event types, etc.).

# List content entries
framedash content list

# Import content from a JSON file
framedash content import ./game-content.json

# Delete by UUID
framedash content delete <uuid>

# Delete by type and content ID
framedash content delete --type weapon --content-id ak47

Usage in CI/CD

GitHub Actions example:

- name: Upload maps and import content
  env:
    FRAMEDASH_API_KEY: ${{ secrets.FRAMEDASH_API_KEY }}
    FRAMEDASH_PROJECT_ID: ${{ vars.PROJECT_ID }}
  run: |
    framedash map-capture --input-dir ./map-captures --upload
    framedash content import ./game-content.json

For Jenkins and TeamCity examples, see the CI/CD Integration Guide.

Next Steps

• API Reference — REST API details
• CI/CD Integration — Jenkins and TeamCity pipeline examples
• CI Profiling — Automated performance profiling setup