Drata CLI

Unofficial generated CLI for Drata's public API surface, sourced from Drata's official OpenAPI documents.

This project is maintained independently and is not affiliated with, endorsed by, or sponsored by Drata. Drata is a trademark of its respective owner. Bundled OpenAPI specs are sourced from Drata's public developer portal at developers.drata.com and remain subject to Drata's terms and copyrights.

The current repository includes both:

• v2 (recommended by Drata)
• v1 (legacy but still publicly documented)

Why this shape

Drata's API is large and still evolving. Instead of hand-writing endpoint wrappers, this CLI loads the official OpenAPI specs and exposes the full operation set through:

• drata ops to discover operations
• drata describe to inspect a specific operation
• drata v1 ... / drata v2 ... to invoke any operation

That keeps the CLI aligned with the published API surface while still being usable from the terminal.

Agent-friendly features

The CLI is designed to work well with automation and coding agents:

• --json on ops, describe, and request commands for structured output
• JSON error envelopes on failures when --json is present
• --dry-run to preview the exact request without sending it
• --input to pass a whole request as a JSON object
• agent-schema to emit a compact machine-readable contract for the CLI and every operation
• Operation discovery and schema inspection sourced from the published OpenAPI specs
• completion bash|zsh|fish for shell completions driven by the same operation registry

Requirements

• Node.js 20+
• A Drata API key

Stability

This is a 0.2.x release. The CLI is intended to be usable, but the public contract may still change before 1.0.0, especially generated operation aliases, request flag naming for newly refreshed specs, and the exact JSON envelope shape for machine-readable output.

Agent Integrations

The CLI is designed to be used directly by coding agents. Install the CLI first:

npm install -g drata-cli

Then configure auth without putting API keys in prompts or shell history:

drata auth login --api-key-stdin
drata auth status --json

Pi

The npm package declares skills/drata-cli-workflow/SKILL.md in its pi.skills manifest, so Pi can discover the workflow when installed as a Pi package:

pi install npm:drata-cli

For local development from a checkout:

npm link
pi install /path/to/drata-cli

You can then ask Pi to use the Drata CLI, or explicitly load the skill:

/skill:drata-cli-workflow

Claude Code

If your Claude Code setup supports Agent Skills, install the bundled skill into your Claude skills directory:

mkdir -p ~/.claude/skills/drata-cli-workflow
cp skills/drata-cli-workflow/SKILL.md ~/.claude/skills/drata-cli-workflow/SKILL.md

For repo-local guidance, GitHub checkouts include CLAUDE.md as a symlink to AGENTS.md, so Claude Code and other agents share one set of instructions. In another repository, copy or adapt AGENTS.md/CLAUDE.md and make sure drata is available on PATH.

OpenAI Codex

For Codex CLI-style project guidance, use AGENTS.md. The npm package includes AGENTS.md, and GitHub checkouts also include the repo-local CLAUDE.md symlink for Claude Code. In another repository, copy or adapt AGENTS.md and make sure drata is available on PATH.

For OpenAI-style agent configuration, see agents/openai.yaml.

OpenCode

OpenCode reads AGENTS.md automatically when working in this repository, so repo-local Drata tasks need no extra setup.

To install the Drata CLI workflow skill globally (available in any project):

npx skills add ethanolivertroy/drata-cli --skill drata-cli-workflow -g

For local development from a checkout:

npx skills add /path/to/drata-cli --skill drata-cli-workflow

Once installed, OpenCode can discover and load the skill for Drata or GRC tasks.

Install

npm install -g drata-cli

Or run it directly with npx:

npx drata-cli --help

Develop locally

npm link

Or run it without linking:

node ./src/cli.mjs --help

Auth and config

The CLI reads auth and routing from:

• DRATA_API_KEY
• DRATA_REGION with us, eu, or apac
• DRATA_BASE_URL to override the region mapping completely
• DRATA_DEFAULT_VERSION with v2 by default, used when you call drata <operation> without an explicit version
• DRATA_ENV_FILE to load a specific env file before .env.local and .env
• DRATA_API_KEY_CMD to fetch the API key from a secret-manager command
• DRATA_READ_ONLY=1 to block mutating API requests

DRATA_API_KEY_CMD runs an arbitrary shell command through your login shell; only set it to a trusted command that you control.

Examples:

export DRATA_API_KEY=drata_xxx
export DRATA_REGION=us
export DRATA_DEFAULT_VERSION=v2

For local use, copy .env.example to .env.local and fill in DRATA_API_KEY. The CLI automatically loads .env.local and .env from the current working directory without overriding already-exported environment variables.

For stronger local secret storage on macOS, store the key in Keychain and optionally validate it against the API:

drata auth login --api-key-stdin
drata auth status
drata auth check --json
drata auth logout

Keychain auth is macOS-only. On Linux and Windows, use DRATA_API_KEY_CMD, --api-key-file, --api-key-stdin, or DRATA_API_KEY instead.

For CI or secret-manager workflows, avoid putting keys in shell history:

op read op://vault/drata/api-key | drata get-company --api-key-stdin
drata get-company --api-key-file /run/secrets/drata_api_key
DRATA_API_KEY_CMD='op read op://vault/drata/api-key' drata get-company
DRATA_READ_ONLY=1 drata get-company

Discover operations

List all documented v2 operations:

drata ops v2

Or skip the version on normal calls and let the CLI resolve it:

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

Versionless calls prefer DRATA_DEFAULT_VERSION and automatically fall back to the other version when that is the only match.

Filter by tag or search text:

drata ops v2 --tag "Controls"
drata ops v2 --search evidence

Describe a single operation:

drata describe get-company
drata describe v2 get-company
drata describe v1 GRCPublicController_editControl
drata describe v2 get-company --json
drata agent-schema v2 --search company

Curated compliance workflows

In addition to raw OpenAPI operations, the CLI includes read-only workflow commands for common compliance triage. These commands use the same auth, region, retry, timeout, JSON, and compact flags as request commands.

drata summary --json --compact
drata controls failing --json --compact
drata controls get DCF-71 --json --compact
drata monitors failing --json --compact
drata monitors for-control DCF-71 --json --compact
drata monitors get 31 --workspace-id 12 --json --compact
drata connections list --status DISCONNECTED --json --compact
drata personnel issues --json --compact
drata personnel get --email alice@example.com --json --compact
drata evidence list --workspace-id 12 --json --compact
drata evidence expiring --days 60 --workspace-id 12 --json --compact

These workflows use v1 list endpoints where they provide workspace-independent compliance rollups and automatically follow page/limit pagination. --limit N caps displayed items in workflow outputs without changing the underlying summary counts or API page size. Use --max-pages N to bound collection work for very large tenants.

Invoke operations

Simple GET

drata v2 get-company

Path and query params

drata v2 list-assets --size 100 --expand device --expand owner
drata v2 get-control-by-id --workspace-id 12 --control-id 34

You can also use the generic forms:

drata v2 get-control-by-id --path workspaceId=12 --path controlId=34
drata v2 list-assets --query size=100 --query "expand[]=device"

JSON request bodies

drata v2 create-asset --body @./examples/asset.json
drata v1 edit-control --workspace-id 12 --control-id 34 --body '{"name":"Access Review","description":"Quarterly review"}'

Machine-readable invocation

For agent workflows, add --json to wrap the request and response in a stable envelope:

drata v2 get-company --json
drata v2 get-control-by-id --workspace-id 12 --control-id 34 --dry-run --json

JSON input mode

Instead of passing many flags, you can provide a single JSON request object:

drata v2 get-control-by-id --input @./request.json --json

Example request.json:

{
  "path": {
    "workspaceId": 12,
    "controlId": 34
  },
  "params": {
    "expand": ["owner", "evidence"]
  },
  "dryRun": true
}

Supported top-level --input fields:

• apiKey
• apiKeyFile
• apiKeyStdin
• region
• baseUrl
• accept
• headers
• path
• query
• params
• named
• form
• body
• allPages
• maxPages
• raw
• output
• dryRun
• readOnly
• retry
• timeoutMs
• json

Agent Schema

agent-schema emits a compact JSON contract for automation and tool wrappers.

drata agent-schema
drata agent-schema v2 --search company

The payload includes:

• supported API versions
• shared request flags
• shell completion support
• per-operation aliases, parameters, request body formats, and response status codes

Multipart endpoints

drata v2 upload-risk-documents --risk-register-id 12 --risk-id 34 --form files=@./risk.pdf

Cursor pagination

For cursor-based list endpoints, you can ask the CLI to keep following pagination.cursor:

drata v2 list-assets --size 100 --all-pages
drata v2 list-assets --size 100 --all-pages --max-pages 25

The CLI stops if a cursor repeats and caps --all-pages at 100 pages by default.

Downloads and alternate response types

For endpoints that can return CSV, HTML, or other text responses, set Accept directly and write the raw response to a file:

drata v1 get-monitor-failed-results-report \
  --workspace-id 12 \
  --test-id 34 \
  --type csv \
  --accept text/csv \
  --output failures.csv

For Drata document downloads, most download operations return a short-lived signed URL instead of streaming the file through the API:

drata v1 get-current-published-policy-pdf-download-url --id 75 --json
drata v1 evidence-library-get-evidence-download-url --workspace-id 12 --evidence-id 34 --version-id 56 --json

Fetch the returned signedUrl separately to save the document.

Shell Completion

Generate a completion script for your shell:

drata completion bash
drata completion zsh
drata completion fish

Example for zsh:

drata completion zsh > ~/.zfunc/_drata
autoload -Uz compinit && compinit

Helpful flags

• --api-key ...
• --api-key-file /run/secrets/drata_api_key
• --api-key-stdin
• --region us|eu|apac
• --base-url https://...
• --accept text/csv
• --header key=value
• --query key=value
• --path key=value
• --param key=value
• --body @file.json
• --input @request.json
• --form key=value
• --form file=@/path/to/file.pdf
• --all-pages
• --max-pages 100
• --raw
• --output response.json
• --dry-run
• --read-only
• --json
• --compact for curated workflow commands
• --limit 10 for curated workflow displayed items
• --retry 2
• --timeout-ms 30000

Refreshing the specs

To pull the latest published Drata specs into specs/:

npm run refresh-specs

This script fetches Drata's official page metadata and extracts the embedded OpenAPI definition for both versions.