drata-cli-workflow

name	drata-cli-workflow
description	Use when querying or changing Drata/GRC data through the `drata` CLI, including compliance status, frameworks, certificates, Trust Center documents, controls, monitoring tests, evidence, risks, vendors, policies, personnel compliance, and background-check questions. Prefer versionless CLI commands, JSON output, read-only mode for reporting, secure auth sources, and dry-runs before mutations.

Drata CLI Workflow

The drata CLI is a generated command-line client for Drata's public API, backed by Drata's published OpenAPI specs.

When working with Drata/GRC data, prefer the drata CLI over hand-written curl, one-off fetch scripts, or an MCP server unless the user explicitly asks for a different integration path. Make sure drata is available on PATH (install with npm install -g drata-cli or run via npx drata-cli). If you are working inside the drata-cli repository itself and drata is not linked on PATH, use node ./src/cli.mjs.

For reporting, investigation, and status questions, default to read-only execution:

DRATA_READ_ONLY=1 drata get-company --json
drata list-personnel --read-only --json

Default workflow

1. Discover operations with drata ops --search ... --json or drata agent-schema ....
2. Inspect the chosen operation with drata describe <operation> --json.
3. For writes, preview the request with drata <operation> ... --dry-run --json.
4. Run the real command only after the request shape looks correct.

Use --json for data that an automation agent or another tool will parse. Use --retry 2 for read-only commands that may hit transient rate limits or 5xx responses. Use --all-pages --max-pages N when collecting paginated data.

Auth and secrets

• Prefer Keychain (drata auth login on macOS), --api-key-stdin, --api-key-file, or DRATA_API_KEY_CMD over putting API keys directly in shell commands.
• DRATA_API_KEY remains supported, and the CLI auto-loads .env.local/.env from the current working directory.
• Treat DRATA_API_KEY_CMD as trusted configuration only; it runs an arbitrary shell command through the user's login shell.
• Never print, commit, or persist real API keys. Dry-run output redacts sensitive request headers.
• Check auth with drata auth status --json before assuming an API key is available.

Version handling

Use versionless commands first:

drata get-company
drata edit-control --workspace-id 12 --control-id 34 --body '{"name":"Access Review"}'

The CLI prefers v2 by default and falls back to v1 only when that is the only match. Only force v1 or v2 explicitly when:

• the user asks for a specific API version
• behavior differs across versions and needs to be pinned
• an operation alias is genuinely ambiguous

If needed, the default can be changed with DRATA_DEFAULT_VERSION=v1|v2.

Common GRC recipes

Use a GRC engineering posture: prefer automation, GRC-as-code, measurable risk outcomes, continuous assurance, stakeholder-friendly outputs, and shared ownership. Turn one-off audit questions into reusable JSON queries whenever possible.

Find the workspace first when a request needs a workspace id:

drata list-workspaces --size 100 --json

Answer certificate, audit artifact, or Trust Center document questions:

drata get-all-private-documents --workspace-id <workspace-id> --json

Answer enabled-framework questions:

drata get-frameworks --workspace-id <workspace-id> --size 100 --all-pages --json

Answer compliance status and monitoring questions:

drata get-controls --workspace-id <workspace-id> --size 100 --all-pages --max-pages 20 --json
drata list-monitors --workspace-id <workspace-id> --size 100 --all-pages --max-pages 20 --json

Answer personnel, compliance-check, or background-check questions:

drata list-personnel --size 100 --all-pages --max-pages 20 --expand user --expand complianceChecks --json

Save raw report responses when the endpoint itself returns CSV, HTML, text, or another file-like response:

drata <operation> --accept <content-type> --output <path>

For Drata document downloads, most download operations return a short-lived signedUrl rather than streaming the file through the API. First request the signed URL, then fetch that URL to the target file:

drata evidence-library-get-evidence-download-url --workspace-id <workspace-id> --evidence-id <evidence-id> --version-id <version-id> --json
drata get-current-published-policy-pdf-download-url --id <policy-id> --json

Continuous assurance triage:

drata list-monitors --workspace-id <workspace-id> --check-result-status FAILED --expand controls --size 100 --all-pages --json
drata list-monitors --workspace-id <workspace-id> --check-result-status ERROR --expand controls --size 100 --all-pages --json
drata list-evidence-library --workspace-id <workspace-id> --statuses NEEDS_ARTIFACT --statuses EXPIRED --statuses NEEDS_ATTENTION --expand controls --size 100 --all-pages --json

Stakeholder-ready control packets:

drata get-controls --workspace-id <workspace-id> --expand owners --expand requirements --expand evidenceIds --expand testIds --size 100 --all-pages --json
drata list-policies --statuses OUTDATED --expand owner --size 100 --all-pages --json

Risk outcome review:

drata list-risk-registers --size 100 --all-pages --json
drata list-risks --risk-register-id <risk-register-id> --status ACTIVE --min-score 10 --expand owners --expand controls --size 100 --all-pages --json
drata list-risks --risk-register-id <risk-register-id> --treatment-plan UNTREATED --expand owners --size 100 --all-pages --json

Vendor trust and supply-chain posture:

drata get-vendor-stats --expand hasPii --expand passwordPolicy --expand risk --expand impactLevel --json
drata list-vendors --risk HIGH --expand latestSecurityReviews --expand documents --size 100 --all-pages --json
drata list-vendors --impact-level CRITICAL --expand latestSecurityReviews --expand documents --size 100 --all-pages --json

GRC-as-code snapshots for review or diffs:

DRATA_READ_ONLY=1 drata get-frameworks --workspace-id <workspace-id> --size 100 --all-pages --json
DRATA_READ_ONLY=1 drata get-controls --workspace-id <workspace-id> --expand frameworkTags --expand requirements --size 100 --all-pages --json
DRATA_READ_ONLY=1 drata list-evidence-library --workspace-id <workspace-id> --expand controls --size 100 --all-pages --json

Write workflow

Prefer structured input for large writes:

drata <mutating-operation> --input @request.json --dry-run --json
drata <mutating-operation> --input @request.json --json

For smaller writes, inline JSON is fine, but always dry-run first. Use explicit --path, --query, or --param flags if a parameter name is unclear.

Output hygiene

• Summarize counts and status first; list names, emails, or other personnel details only when the user asks for them or they are necessary to answer.
• Avoid saving raw API responses with personnel data unless needed for the task. Delete temporary files when they are no longer useful.
• Do not expose session headers, API keys, or token-like values in the final answer.

Discovery shortcuts

drata ops --search controls --json
drata agent-schema --search controls
drata describe get-control-by-id --json

When not to overcomplicate

• Do not reach for MCP just to make the CLI "agent friendly". This CLI plus structured JSON output is the default path here.
• Do not handcraft API requests when the CLI already exposes the operation.
• Do not force version-specific commands unless there is a real reason.