--- title: "CLI" canonical_url: "https://docs.getdx.com/cli/" md_url: "https://docs.getdx.com/cli.md" last_updated: "2026-05-22" --- # 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](https://docs.getdx.com/catalog/overview/), configure [Scorecards](https://docs.getdx.com/scorecards/overview/), run [Data Studio](https://docs.getdx.com/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](https://docs.getdx.com/mcp/). Both interfaces remain supported.
## Get started The DX CLI can be installed via npm: ```shell npm install -g @get-dx/cli ``` Run `dx init` to authenticate and optionally install the agent skill: ```shell dx init ``` ## Available commands Each command calls a corresponding [Web API method](https://docs.getdx.com/webapi/overview/) and inherits its scope requirements. Run `dx --help` for the full command tree, and `dx --help` for usage and examples on any specific command. ### auth Manage CLI authentication and inspect the active session. ```shell 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](https://docs.getdx.com/catalog/overview/). ```shell 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. ```shell 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](https://docs.getdx.com/scorecards/overview/) as YAML, including listing, inspecting, creating, updating, and deleting. ```shell 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](https://docs.getdx.com/snapshots/overview/) results, including team scores, driver comments, and CSAT comments. The comment list commands paginate with `--cursor` and `--limit` (max 100). ```shell 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](https://docs.getdx.com/data-studio/) SQL queries with parameterized variables and table, JSON, or CSV output. ```shell 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`. ### teams Look up DX teams by ID, by reference ID, or by member emails. ```shell 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](https://docs.getdx.com/self-service/overview/) workflow definitions, optionally filtered by scope or by a specific entity. ```shell 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](https://vercel.com/changelog/introducing-skills-the-open-agent-skills-ecosystem) 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 ` 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](https://docs.getdx.com/webapi/overview/#authentication) and [personal access tokens](https://docs.getdx.com/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: ```shell dx --json catalog entities list ``` ## Dedicated and managed deployments Pass your hostname to `dx init` to point the CLI at a DX dedicated or DX managed instance: ```shell dx init --host mycompany.getdx.io ``` The CLI resolves `.getdx.io` to a DX dedicated instance automatically. Any other custom domain is treated as DX managed and prompts for the API base URL separately. The same value can be supplied via the `DX_HOST` environment variable. ## Logging Logs are off by default. Set `DX_LOG_LEVEL` to one of `debug`, `info`, `warn`, or `error` to enable them: ```shell 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. --- ## Sitemap [Overview of all docs pages](/llms.txt)