--- title: "CLI" canonical_url: "https://docs.getdx.com/cli/" md_url: "https://docs.getdx.com/cli.md" last_updated: "2026-09-29" --- # 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, and more. It is designed to be accessed either through your AI agent, or from a terminal or CI pipeline. The DX CLI is a command tool that sends requests to DX APIs and returns results. It is not an AI agent and does not interpret, reason about, or generate data on its own. > **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. ## About the CLI The DX CLI provides a headless way to query DX data and perform operations in DX directly from your terminal, CI/CD pipelines, or agentic workflows -- all without going into the DX UI. - **For engineers**: Run straightforward commands to interact with DX APIs, query metrics, and make updates directly from your terminal or automation scripts. - **For agents**: The CLI includes built-in skills and context that teach agents when, why, and how to use DX APIs. This allows agents to translate high-level natural language prompts into exact DX actions. For example, instead of running `dx scorecards create --from-file ./my-scorecard.yaml`, you can simply ask your agent: "Build a scorecard that checks for README.md existence." ## Advantages of the CLI The DX CLI provides you with the ability to interact with DX seamlessly through your agent, and gives your agent the exact context and tool definitions it needs to take actions in DX on your behalf. That way, you can bring DX data and actions directly into the tools and environments where your team already works. The DX CLI allows you to: 1. Get data _out_ of DX (such as report results, trends, and team rollups) and into your pipeline for other operations 2. Make changes _in_ DX (create new reports, create new scorecards, add/edit catalog entities) in a quick, automated way without going into the DX UI. ## Ways to use the CLI You can do the following with the DX CLI: Query data from Data Studio, export it to use elsewhere/in another application Take your DX data wherever it's needed. Your agent can query data from Data Studio and make it available in a format that works for you (i.e. a JSON file), or pipe it directly into another step in your development workflow. For example, you can turn the latest DX Snapshot into a CSV to provide high-level updates to execs all without writing any code. Build reports in DX from a simple prompt Instead of manually constructing a report in DX, writing multiple SQL queries, and fixing formatting, you can ask your agent to build a report in DX based on any available data in Data Studio. If you're not sure what data is available, your agent can answer that as well. Add catalog entities to DX or edit existing catalog entities in an automated manner Manage entities for your catalog in an automated way - that can include adding many entities at once asynchronously, or making mass-edits across all entities without any of the work. Either of these can be accomplished by simply prompting your agent to do so. Build scorecards based on friction that occurs in your development workflow Instead of writing SQL for scorecard checks, describe what you want to measure and let your agent build it for you. This keeps you in your flow—if you identify a new check during development, like an updated production readiness requirement, you can prompt your agent to update the scorecard immediately without context switching. ## Video overview The following Loom walks through how to set up and use the DX CLI from start to finish.
## Get started > Note: The DX CLI requires Node v20 or later. 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 ``` 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: ```shell npm update --g @get-dx/cli ``` ## 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`. ### studio reports Create and manage [Data Studio reports](https://docs.getdx.com/data-studio/#custom-reports) using SQL queries with parameterized variables to build customized metrics and visualizations you can share with your team. ```shell 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. ```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 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: ```shell # 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: ```shell # 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: ```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)