dx-cli

DX CLI

Use the dx CLI to manage your organization's Software Catalog, Scorecards, and Engineering data from the command line. All commands communicate with the DX web API and require authentication.

Getting Help

Run dx --help to see all top-level commands. Run dx <subcommand> --help to see usage for any command:

dx --help
dx attributeGroups --help
dx auth --help
dx catalog --help
dx catalog entities --help
dx catalog entityTypes --help
dx scorecards --help
dx studio --help

All commands accept --json to return machine-readable JSON instead of human-readable output.

Authentication

Before using a dx subcommand for the first time, verify that you are authenticated:

dx auth status

If this returns an error or shows that you are not logged in, stop and ask the user to login interactively with dx init, or non-interactively with dx auth login.

If you need information about the currently authenticated user and their team to include in a query, run:

dx auth whoami

This calls the /auth.whoami endpoint and displays the account name, token type, and (for personal access tokens) the user's name, email, and team with its lead and contributors. Organization tokens return null for user and team.

Answering DX Product Questions

Use this for any question about DX itself rather than the user's own data: product concepts ("what's the difference between a Scorecard and an Initiative?"), setup/admin procedures ("how do I set up Okta SSO?", "how do I backfill GitHub history?"), connector configuration ("how do I connect GitHub?"), or troubleshooting/FAQ ("why doesn't DX support X?"). Do not use it for questions about the user's own data (their entities, checks, scores, tasks) — use the dx CLI commands in this skill for those instead.

1. Fetch https://docs.getdx.com/llms.txt for the index of documentation pages and their Markdown URLs.
2. Fetch the relevant page's .md URL directly, not the HTML page, e.g. https://docs.getdx.com/onboarding/github-backfill.md.
3. Answer from the fetched Markdown, not from memory. If the page contains a numbered or sequential procedure, follow those steps in the given order — don't skip ahead, reorder, or paraphrase a step away, whether you're relaying them to the user or executing them yourself.

Glossary

Software Catalog terms

Entity — A record in the Software Catalog representing a service, team, library, or any other thing tracked by your organization. Each entity has an identifier (a unique slug), a type, optional name, description, owner_teams, owner_users, and a map of typed properties.

Entity Type — The schema for a category of entities (e.g. service, library). An entity type defines which properties and aliases entities of that type carry.

Property — A typed field defined on an entity type. Properties have identifiers and types such as text, number, boolean, select, multi_select, url, date, user, list, json, and others. When setting properties with --property, use key=value syntax; for multi_select and list types, values are comma-separated.

Alias — An alternative identifier that maps external system references (e.g. a GitHub repo slug) to an entity.

Scorecards terms

Scorecard — A health-tracking framework that evaluates entities against a set of checks. Scorecards are either LEVEL-based (entities are ranked across named levels like Bronze/Silver/Gold) or POINTS-based (entities accumulate points from checks). To see how a specific entity is currently performing across all scorecards, use dx catalog entities scorecards <identifier>.

Check — A single SQL-based rule inside a scorecard. The SQL query returns a status column (PASS, WARN, or FAIL) for each entity.

Initiative — A time-boxed project that groups failing scorecard checks into actionable tasks for teams. Tasks for a given entity can be fetched with dx catalog entities tasks <identifier>.

Exemption — A time-bound approved pass on a failing check for a specific entity. A check result with a non-null exemption_expires_at is exempted: it may still be failing, but is not counted against the entity until the exemption expires.

Snapshot terms

Attribute group — A user attribute used to segment snapshot reporting, such as location, tenure band, or coding activity level. Groups are either DX managed (maintained by DX, such as tenure band and coding activity level), admin managed (imported from the users CSV), or self-reported (custom questions answered during a snapshot). Use dx attributeGroups list to retrieve attribute group IDs and the attribute value IDs nested inside them. position is display order only, and most attribute groups have none; attribute groups and values without a position sort last. Hidden and privileged attribute groups are flagged in the output.

Attribute value — A selectable value within an attribute group, such as "5+ years" within tenure band. Attribute value IDs feed the attribute_ids filter when querying snapshot scores by attribute.

Data Studio terms

Report — A saved collection of tiles (see dx studio reports), organized on a dedicated page for dashboards and sharing.

Tile — A single saved query and chart configuration within a report. Each tile's SQL can reference report variables.

Variable — A named, $-prefixed placeholder (e.g. $team_ids) that a report's tile SQL can reference for interactive filtering. Built-in variables ($service_ids, $team_ids, $tag_ids, $user_ids, $repo_ids, $start_date, $end_date) are provided out of the box and just need to be toggled on. Custom variables are account-defined dropdown filters backed by a SQL query that returns value and label columns. Variables cannot be managed through the CLI/API — enabling/disabling built-ins and adding/updating/deleting custom variables must be done in the Data Studio UI — but once enabled on a report, any tile's SQL (including tiles set via dx studio reports create/update) can reference them.

Reference Docs

• Catalog management — Entities and entity types: listing, inspecting, creating, updating, and deleting.
• Report creation — Studio reports: initializing YAML, creating reports, and updating existing reports.
• Scorecards management — Scorecards and checks: listing, inspecting, creating, updating, and deleting via YAML.
• Failing checks — Review and resolve an entity's failing scorecard checks: triage, diagnosis, fixes, and re-evaluation.
• Snapshot analysis — Analyze snapshot scores, teams, driver comments, and CSAT comments.

Snapshot teams

Use dx snapshots snapshotTeams list --id <snapshot_id> to list the teams captured in a snapshot.

• id is the Snapshot Team ID. It is only valid within that snapshot and is what DX score endpoints expect in the snapshot_team_ids filter.
• team_id is the stable DX team ID. It can be used with dx teams info --team-id <team_id> to inspect the current DX team record.
• Use --json to return the raw API response unchanged.