CLI

The DX CLI is an AI-native command-line tool for interacting with DX from the terminal. With it you can manage your Software Catalog, configure Scorecards, run Data Studio queries, look up DX teams, and more—from a developer’s terminal, an AI agent, or a CI pipeline.

Note: The DX CLI is in beta. DX intends for the CLI to become the primary interface for AI agents and is investing in it as the long-term direction beyond the MCP server. Both interfaces remain supported.

Get started

Note: The DX CLI requires Node v20 or later.

The DX CLI can be installed via npm:

npm install -g @get-dx/cli

Run dx init to authenticate and optionally install the agent skill:

dx init

The DX CLI automatically checks for the latest version every 24 hours before running a command. If a new version is available, you will be prompted to upgrade, be reminded later, or skip that version.

To manually update to the latest version of the CLI:

npm update --g @get-dx/cli

Available commands

Each command calls a corresponding Web API method and inherits its scope requirements. Run dx --help for the full command tree, and dx <command> --help for usage and examples on any specific command.

auth

Manage CLI authentication and inspect the active session.

dx auth login
dx auth login --token [TOKEN]
dx auth status
dx auth logout

Required scope: none.

catalog entities

List, inspect, create, update, upsert, and delete entities in the Software Catalog.

dx catalog entities list
dx catalog entities info [identifier]
dx catalog entities create --type service --identifier [identifier]
dx catalog entities upsert --type service --identifier [identifier]
dx catalog entities update [identifier] --property tier=Tier-1
dx catalog entities update [identifier] --alias github_repo=12345
dx catalog entities delete [identifier]
dx catalog entities tasks [identifier]
dx catalog entities scorecards [identifier]

--property and --alias accept key=value pairs and can be repeated to set multiple values. On update and upsert, pass --alias key=null to remove an alias.

Required scopes: catalog:read for list, info, tasks, scorecards; catalog:write:entities for create, update, upsert, delete.

catalog entityTypes

List, inspect, create, update, and delete entity type definitions, or initialize a YAML template for editing.

dx catalog entityTypes list
dx catalog entityTypes info [identifier]
dx catalog entityTypes init ./my-entity-type.yaml
dx catalog entityTypes create --from-file ./my-entity-type.yaml
dx catalog entityTypes update [identifier] --from-file ./my-entity-type.yaml
dx catalog entityTypes delete [identifier]

Required scopes: catalog:read for list, info, and init with --identifier; catalog:write:entities for create, update, delete.

scorecards

Manage Scorecards as YAML, including listing, inspecting, creating, updating, and deleting.

dx scorecards list
dx scorecards info [id]
dx scorecards init ./my-scorecard.yaml
dx scorecards create --from-file ./my-scorecard.yaml
dx scorecards update [id] --from-file ./my-scorecard.yaml
dx scorecards delete [id]

Required scopes: scorecards:read for list, info, and init with --id; scorecards:write for create, update, delete.

snapshots

Inspect Snapshot results, including team scores, driver comments, and CSAT comments. The comment list commands paginate with --cursor and --limit (max 100).

dx snapshots list
dx snapshots info --id [snapshot_id]
dx snapshots driverComments list --id [snapshot_id] --limit 100
dx snapshots csatComments list --id [snapshot_id] --limit 100

Required scope: snapshots:read.

studio query

Run Data Studio SQL queries with parameterized variables and table, JSON, or CSV output.

dx studio query 'SELECT id, name FROM github_repositories LIMIT 10'
dx studio query 'SELECT * FROM github_pulls' --output pulls.csv
dx studio query 'SELECT * FROM github_repositories WHERE id IN ($repo_ids)' --variable repo_ids=1,2,3

Required scope: datacloud:query.

studio reports

Create and manage Data Studio reports using SQL queries with parameterized variables to build customized metrics and visualizations you can share with your team.

dx studio reports create
dx studio reports info [id]
dx studio reports init [path]
dx studio reports list
dx studio reports update [id]

Required scopes: studio:reports:write for create, update, and delete; studio:reports:read for info and list.

teams

Look up DX teams by ID, by reference ID, or by member emails.

dx teams list
dx teams info --team-id [id]
dx teams info --reference-id [id]
dx teams findByMembers --team-emails person@example.com,another@example.com

Required scope: snapshots:read.

workflows

List Self-service workflow definitions, optionally filtered by scope or by a specific entity.

dx workflows list
dx workflows list --scope GLOBAL
dx workflows list --scope ENTITY --entity-identifier [identifier]

Required scope: workflows:read.

For agents

The DX CLI is designed for headless use from the ground up, ready for integration into your agentic workflows.

Agent skill

dx init offers to install the bundled dx-cli agent skill, which teaches skills-compatible agents how and when to invoke the CLI, including the available commands, argument shapes, and DX glossary.

The skill bundles workflow guides for managing the Software Catalog, managing Scorecards, and analyzing Snapshot results.

Non-interactive authentication

Agents can authenticate the CLI in one of two ways:

• Set the DX_API_TOKEN environment variable for the session or job. The CLI uses this token for all commands without saving it to the OS keyring.
• Alternatively, run dx auth login --token <token> once at the start of the session to store the token in the OS keyring. Subsequent commands use this stored token.

The CLI accepts both organization tokens and personal access tokens. DX recommends personal access tokens for individuals and agents because they attribute calls to the issuing user in audit logs. Use organization tokens for machine-to-machine workflows that are not tied to a user.

Machine-readable output

Pass --json to any command to receive the raw API response as machine-readable JSON instead of the formatted human view:

dx --json catalog entities list

Dedicated and managed deployments

The CLI relies on an API base URL for making requests and a web base URL for displaying links on resources. The default values are used for DX cloud deployments. Users of dedicated and managed deployments will need to specify these values explicitly when authenticating.

Value	How it is used	Env var	Default value
Web base URL	Browser-based login and displaying web links	DX_WEB_BASE_URL	https://app.getdx.com
API base URL	Making each API request to DX	DX_API_BASE_URL	https://api.getdx.com

For dedicated deployments

Set the env vars once when initializing:

# Interactive login
DX_WEB_BASE_URL="https://mycompany.getdx.io" DX_API_BASE_URL="https://api.mycompany.getdx.io" dx init

# Non-interactive use for CI, containers, or remote agents
DX_WEB_BASE_URL="https://mycompany.getdx.io" DX_API_BASE_URL="https://api.mycompany.getdx.io" DX_API_TOKEN="$DX_TOKEN" dx auth login

For managed deployments

Set the env vars once when initializing:

# Interactive login
DX_WEB_BASE_URL="https://dx.some-example-subdomain.example.com" DX_API_BASE_URL="https://api.dx.some-example-subdomain.example.com" dx init

# Non-interactive use for CI, containers, or remote agents
DX_WEB_BASE_URL="https://dx.some-example-subdomain.example.com" DX_API_BASE_URL="https://api.dx.some-example-subdomain.example.com" DX_API_TOKEN="$DX_TOKEN" dx auth login

Logging

Logs are off by default. Set DX_LOG_LEVEL to one of debug, info, warn, or error to enable them:

DX_LOG_LEVEL=debug dx catalog entities list

Logs are human-readable on a TTY and switch to JSON when --json is passed or when stderr is redirected.