Dash0 CLI

A command-line interface designed for humans, agentic AIs and CI/CD to interact with the Dash0 observability platform.

An ergonomic CLI for agentic AI

The dash0 CLI is designed to be driven by AI coding agents as naturally as by humans. Its capabilities are discoverable via --help, alongside a comprehensive command reference with detailed flags, expected outputs, and ready-to-use workflow examples. Authentication and connection settings can be configured entirely through profiles and environment variables, avoiding the need to pass secrets as command-line arguments. Commands use consistent naming conventions and flags. Structured and parseable output formats (--output json, --output yaml, --output csv). Agent mode makes all of this automatic: JSON output, structured help, JSON errors, no prompts, and no colors — with zero configuration.

Installation

Homebrew (macOS and Linux)

brew install --cask dash0hq/dash0-cli/dash0

No brew tap, no brew trust, no extra ceremony. The qualified install path taps the dash0hq/homebrew-dash0-cli repository on first use.

Note

If you previously installed dash0 from the legacy formula (brew install dash0 after brew tap dash0hq/dash0-cli <URL>), see the Homebrew tap migration notes for the one-time switch to the new cask.

GitHub Releases

Download pre-built binaries for your platform from the releases page. Archives are available for Linux, macOS and Windows across multiple architectures.

GitHub Actions

Setup Action

Use the dash0 CLI in your CI/CD workflows with the setup action:

steps:
  - uses: actions/checkout@v4

  - name: Setup Dash0 CLI
    uses: dash0hq/dash0-cli/.github/actions/setup@main  # You can use any git ref: @main, @v1.1.0, or @commit-sha
    # with:
    #   version: '1.1.0' # 1.1.0 is the earliest supported version

  - name: List dashboards
    env:
      DASH0_API_URL: ... # Find this at https://app.dash0.com/goto/settings/endpoints?endpoint_type=api_http
      DASH0_OTLP_URL: ... # Find this https://app.dash0.com/goto/settings/endpoints?endpoint_type=otlp_http
      DASH0_AUTH_TOKEN: ... # Get one from https://app.dash0.com/goto/settings/auth-tokens?auth_token_id=39d58aa9-b64e-464c-a675-cc3923085d6c ; keep the auth token in a GitHub secret!
      DASH0_DATASET: my-dataset # Leave empty for the `default` dataset
    run: dash0 dashboards list

Send Log Event Action

The send-log-event action sends log events to Dash0 directly from your workflows. It is standalone: it installs the Dash0 CLI automatically if it is not already on PATH. If the setup action has already run in the same job, the existing installation is reused.

When used on its own, pass otlp-url and auth-token directly:

steps:
  - name: Send deployment event
    uses: dash0hq/dash0-cli/.github/actions/send-log-event@main
    with:
      otlp-url: ${{ vars.DASH0_OTLP_URL }}
      auth-token: ${{ secrets.DASH0_AUTH_TOKEN }}
      event-name: dash0.deployment
      body: 'Deployment completed'
      severity-number: '9'
      service-name: my-service
      deployment-environment-name: production
      deployment-status: succeeded

When the setup action has already created a profile, the connection parameters are inherited and do not need to be repeated:

steps:
  - name: Setup Dash0 CLI
    uses: dash0hq/dash0-cli/.github/actions/setup@main
    with:
      otlp-url: ${{ vars.DASH0_OTLP_URL }}
      auth-token: ${{ secrets.DASH0_AUTH_TOKEN }}

  - name: Send deployment event
    uses: dash0hq/dash0-cli/.github/actions/send-log-event@main
    with:
      event-name: dash0.deployment
      body: 'Deployment completed'
      severity-number: '9'
      service-name: my-service
      deployment-environment-name: production
      deployment-status: succeeded

Docker

docker run ghcr.io/dash0hq/cli:latest [command]

Multi-architecture images (linux/amd64, linux/arm64) are published to GitHub Container Registry.

From Source

Requires Go 1.22 or higher.

git clone https://github.com/dash0hq/dash0-cli.git
cd dash0-cli
make install

Usage

For the full command reference with detailed flags, output examples, and AI-agent workflows, see docs/commands.md.

Configuration

The CLI resolves connection settings from profiles stored on disk, environment variables, and CLI flags, in that order. Profiles are the recommended way to manage credentials locally; environment variables are convenient for CI/CD and agentic workflows.

Profiles

Configure API access using profiles. A profile can authenticate with either a long-lived static auth token or via OAuth 2.0 + PKCE (browser-based login). All other profile fields are optional at creation time and can be supplied later via config profiles update or overridden at runtime with environment variables or CLI flags.

Browser-based OAuth login (recommended for human users):

dash0 config profiles create dev --oauth \
    --api-url https://api.us-west-2.aws.dash0.com

dash0 login

dash0 login opens the system browser, completes the OAuth flow, and saves the access and refresh tokens into the profile. Access tokens are refreshed automatically as long as the refresh token is valid; dash0 logout revokes and clears them.

Static-token profile (suited to CI/CD and agent workflows):

dash0 config profiles create dev \
    --api-url https://api.us-west-2.aws.dash0.com \
    --otlp-url https://ingress.us-west-2.aws.dash0.com \
    --auth-token auth_xxx

Manage and inspect profiles:

dash0 config profiles list

dash0 config profiles select dev

dash0 config show

You can find the API endpoint for your organization on the Endpoints page, under the API entry, and the OTLP HTTP endpoint under the OTLP via HTTP entry. Currently only HTTP OTLP endpoints are supported.

Configuration storage

Profiles and the active-profile selection are stored on disk in ~/.dash0/:

File	Content
`profiles.json`	All configured profiles (name, URLs, auth token, dataset, OAuth state)
`activeProfile`	Name of the currently active profile
`oauth-clients.json`	Cached OAuth dynamic client registrations, keyed by API URL

The directory is created automatically when you create your first profile.

To store configuration elsewhere, set the DASH0_CONFIG_DIR environment variable:

export DASH0_CONFIG_DIR=~/.local/dash0
dash0 config profiles create dev --api-url https://api.us-west-2.aws.dash0.com

Agent mode

Agent mode optimizes every aspect of the CLI for machine consumption. Enable it explicitly with --agent-mode or DASH0_AGENT_MODE=true, or let it auto-activate when a known AI agent environment variable is detected:

Agent	Environment variables
Aider	`AIDER`
Claude Code	`CLAUDE_CODE`, `CLAUDECODE`
Cline	`CLINE`, `CLINE_TASK_ID`
Cursor	`CURSOR_AGENT`, `CURSOR_SESSION_ID`
GitHub Copilot	`GITHUB_COPILOT`
MCP servers	`MCP_SESSION_ID`
OpenAI Codex	`CODEX`, `OPENAI_CODEX`
Windsurf	`WINDSURF_AGENT`, `WINDSURF_SESSION_ID`

When agent mode is active, the CLI:

Defaults output to JSON — all data retrieval commands (list, get, query, config show, metrics instant) output JSON instead of tables, without needing -o json.
Returns --help as structured JSON — flags, subcommands, aliases, and metadata are machine-parseable.
Emits errors as JSON on stderr — {"error": "...", "hint": "..."} instead of colored text.
Skips confirmation prompts — destructive operations (delete, remove) proceed without asking, equivalent to --force.
Disables colored output — no ANSI escape codes in any output.

To explicitly disable agent mode (for example, when running inside an agent environment but wanting human-readable output), set DASH0_AGENT_MODE=0 or DASH0_AGENT_MODE=false. This overrides all other activation methods.

See the agent mode specification for the full priority order and details.

Applying assets

Apply asset definitions from a file, directory, or stdin. The input may contain multiple YAML documents separated by ---. Supported asset types: Dashboard, PersesDashboard, CheckRule, PrometheusRule (alerting and recording rules), SyntheticCheck, View, Dash0SpamFilter, and Dash0NotificationChannel.

From a single file:

dash0 apply -f assets.yaml

From a directory (recursive):

dash0 apply -f dashboards/

From stdin:

cat assets.yaml | dash0 apply -f -

Validate without applying:

dash0 apply -f assets.yaml --dry-run

Note: In Dash0, dashboards, views, synthetic checks and check rules are called "assets", rather than the more common "resources". The reason for this is that the word "resource" is overloaded in OpenTelemetry, where it describes "where telemetry comes from".

Asset CRUD commands

Every asset type (dashboards, check-rules, synthetic-checks, views, recording-rules, notification-channels, spam-filters) supports the same five subcommands. Substitute the asset noun in the examples below.

List all assets of a type:

dash0 dashboards list

Get one by ID (in table form):

dash0 dashboards get <id>

Get one by ID (in a re-appliable YAML form):

dash0 dashboards get <id> -o yaml

Create from a YAML file:

dash0 dashboards create -f dashboard.yaml

Update from a YAML file (the ID is read from the file when not passed explicitly):

dash0 dashboards update -f dashboard.yaml

Delete by ID (use --force to skip the confirmation prompt):

dash0 dashboards delete <id>

dashboards create and apply also accept PersesDashboard CRD files; check-rules create and apply also accept PrometheusRule CRD files. See docs/commands.md for the full per-asset reference and the YAML formats.

Logging

Sending logs to Dash0

Note

The dash0 logs send command requires an OTLP URL configured in the active profile, or via the --otlp-url flag or the DASH0_OTLP_URL environment variable.

dash0 logs send "Application started" \
    --resource-attribute service.name=my-service \
    --log-attribute user.id=12345 \
    --severity-text INFO --severity-number 9

Querying logs from Dash0

Note

The dash0 logs query command requires an API URL and auth token configured in the active profile, or via flags or environment variables.

Recent logs (default: last 15 minutes, up to 50):

dash0 logs query

Explicit time range and higher limit:

dash0 logs query --from now-1h --to now --limit 100

Filter by service:

dash0 logs query --filter "service.name is my-service"

Filter by severity range (errors and warnings):

dash0 logs query --filter "otel.log.severity.range is_one_of ERROR WARN"

JSON filter criteria copied from the Dash0 UI:

dash0 logs query --filter '[{"key":"service.name","operator":"is","value":"api"}]'

CSV output for pipelines:

dash0 logs query -o csv

Custom columns:

dash0 logs query --column time --column service.name --column body
dash0 logs query --precision disabled --filter "test.id is <id>"

See the filter syntax reference for the full list of operators. Pass --precision disabled to turn off adaptive sampling when a narrow filter must always return every match.

Tracing

Sending spans to Dash0

Note

The dash0 spans send command requires an OTLP URL configured in the active profile, or via the --otlp-url flag or the DASH0_OTLP_URL environment variable.

dash0 spans send --name "GET /api/users" \
    --kind SERVER --status-code OK --duration 100ms \
    --resource-attribute service.name=my-service

Querying spans from Dash0

Note

The dash0 spans query command requires an API URL and auth token configured in the active profile, or via flags or environment variables.

Recent spans (default: last 15 minutes, up to 50):

dash0 spans query

Explicit time range and higher limit:

dash0 spans query --from now-1h --to now --limit 100

Filter by service:

dash0 spans query --filter "service.name is my-service"

Filter by span status:

dash0 spans query --filter "otel.span.status.code is ERROR"

JSON filter criteria copied from the Dash0 UI:

dash0 spans query --filter '[{"key":"service.name","operator":"is","value":"api"}]'

CSV output:

dash0 spans query -o csv

Custom columns:

dash0 spans query --column otel.span.start_time --column otel.span.duration --column "span name" --column http.request.method
dash0 spans query --precision disabled --filter "test.id is <id>"

See the filter syntax reference for the full list of operators. Pass --precision disabled to turn off adaptive sampling for narrow lookups that must always return every match.

Getting a trace from Dash0

Note

The dash0 traces get command requires an API URL and auth token configured in the active profile, or via flags or environment variables.

Get all spans of a trace:

dash0 traces get <trace-id>

Look back further when the trace is older:

dash0 traces get <trace-id> --from now-2h

Follow span links to related traces:

dash0 traces get <trace-id> --follow-span-links

OTLP JSON output:

dash0 traces get <trace-id> -o json

Custom columns:

dash0 traces get <trace-id> --column otel.span.start_time --column otel.span.duration --column "span name" --column otel.span.status.code

dash0 traces get always disables adaptive sampling so every span in the trace is returned.

Metrics

# Instant query — current request rate per service
dash0 metrics instant --promql 'sum by (service_name) (rate(http_server_request_duration_seconds_count[5m]))'

# Instant query with filters
dash0 metrics instant --filter 'service.name is my-service'

# Output as CSV with specific columns
dash0 metrics instant --promql 'sum by (service_name) (rate(http_server_request_duration_seconds_count[5m]))' -o csv --column value --column service_name

Teams (experimental)

# List all teams
dash0 -X teams list

# Get team details (members + accessible assets)
dash0 -X teams get <id>

# Create a team
dash0 -X teams create "Backend Team" --color-from "#FF6B6B" --color-to "#4ECDC4"

# Add members to a team
dash0 -X teams add-members <team-id> <member-id-1> <member-id-2>

Members (experimental)

# List organization members
dash0 -X members list

# Invite a member (default role: basic_member)
dash0 -X members invite user@example.com

# Delete a member
dash0 -X members delete <member-id> --force

Raw HTTP passthrough (experimental)

The api command calls any Dash0 API endpoint directly, reusing the active profile's connection settings. It is useful for endpoints that do not yet have a dedicated subcommand.

# GET — dataset auto-injected from the active profile
dash0 -X api /api/signal-to-metrics/configs

# POST with a payload from a file
dash0 -X api POST /api/signal-to-metrics/configs -f config.json

# Skip dataset injection for organization-level endpoints
dash0 -X api /api/organization/settings --dataset ""

Local OTLP proxy (experimental)

The otlp proxy command runs a long-lived local OTLP forwarder. It accepts OTLP/HTTP on 127.0.0.1:4318 and OTLP/gRPC on 127.0.0.1:4317 and forwards every batch to Dash0 using the active profile's credentials. An OpenTelemetry SDK at default endpoint configuration connects without any environment variable change, collapsing the local-dev setup from a YAML-heavy Collector config to a single command.

# Just run it. SDK defaults already point at the proxy.
dash0 -X otlp proxy

# Print every forwarded record on stdout in collector-debug-exporter style.
dash0 -X otlp proxy --tail

# Pick non-default ports (e.g., when another local Collector holds the defaults).
dash0 -X otlp proxy --http-port 8318 --grpc-port 8317

# Tag every forwarded batch at the resource level so it is filterable in Dash0.
dash0 -X otlp proxy \
    --resource-attribute developer=alice \
    --resource-attribute deployment.environment.name=local

The proxy exits on Ctrl-C (or SIGTERM) after draining in-flight work within a 5-second deadline. On startup, if either default port is already in use, the proxy exits non-zero with an actionable error that names the holding process. See docs/commands.md for the full reference, including the decoration flags (--scope-attribute, --log-attribute, --span-attribute, --metric-attribute, --scope-name, --scope-version), the agent-mode event schema, and the failure-mode classification.

Common settings

Flag	Short	Env Variable	Description
`--agent-mode`		`DASH0_AGENT_MODE`	Enable agent mode for AI coding agents. Auto-detected when common agent env vars are set.
`--api-url`		`DASH0_API_URL`	Override API URL from profile. Find yours here.
`--otlp-url`		`DASH0_OTLP_URL`	Override OTLP URL from profile. Find yours here.
`--auth-token`		`DASH0_AUTH_TOKEN`	Override auth token from profile. Find yours here.
`--color`		`DASH0_COLOR`	Color mode for output: `semantic` (default) or `none`. Ignored when piping output.
`--dataset`		`DASH0_DATASET`	Override dataset from profile. Use the `identifier`, not `Name`.
`--experimental`	`-X`		Enable experimental features (required for commands marked `[experimental]`)
`--profile`		`DASH0_PROFILE`	Use a named profile for this invocation without changing the active profile.
`--file`	`-f`		Input file path (use `-` for stdin)
`--output`	`-o`		Output format: `table`, `wide`, `json`, `yaml`, `csv`
		`DASH0_CONFIG_DIR`	Override the configuration directory (default: `~/.dash0`)
		`DASH0_OTLP_PROXY_GRPC_PORT`	Override `dash0 otlp proxy --grpc-port`
		`DASH0_OTLP_PROXY_HTTP_PORT`	Override `dash0 otlp proxy --http-port`
`--max-retries`		`DASH0_MAX_RETRIES`	Max retries for failed API requests (default: `3`, max: `5`; `0` to disable)

Output formats

The list and get commands for assets support multiple output formats via -o:

table (default): Compact view with essential columns (name and ID)
wide: Similar to table, with additional columns (dataset, origin, and URL)
json: Full asset data in JSON format
yaml: Full asset data in YAML format
csv: Comma-separated values with the same columns as wide, suitable for piping and automation

The update and apply commands show a unified diff of changes.

The logs query, spans query, and traces get commands support a different set of formats via -o:

table (default): Columnar output (logs query shows timestamp, severity, and body; spans query shows timestamp, duration, name, status, service, and trace ID; traces get shows a hierarchical span tree)
json: Full OTLP/JSON payload
csv: Comma-separated values

In agent mode, all data retrieval commands default to JSON without needing -o json.

Shell completions

Enable tab completion for your shell:

Bash (requires bash-completion):

source <(dash0 completion bash)
# Permanent (macOS): dash0 completion bash > $(brew --prefix)/etc/bash_completion.d/dash0

Zsh:

source <(dash0 completion zsh)
# Permanent (macOS): dash0 completion zsh > $(brew --prefix)/share/zsh/site-functions/_dash0

Fish:

dash0 completion fish | source
# Permanent: dash0 completion fish > ~/.config/fish/completions/dash0.fish

Contributing

See CONTRIBUTING.md for development instructions.

Name		Name	Last commit message	Last commit date
Latest commit History 225 Commits
.chloggen		.chloggen
.github		.github
Formula		Formula
cmd/dash0		cmd/dash0
docs		docs
internal		internal
scripts		scripts
test/roundtrip		test/roundtrip
.editorconfig		.editorconfig
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
STRATEGY.md		STRATEGY.md
TODO.md		TODO.md
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

Dash0 CLI

An ergonomic CLI for agentic AI

Installation

Homebrew (macOS and Linux)

GitHub Releases

GitHub Actions

Setup Action

Send Log Event Action

Docker

From Source

Usage

Configuration

Profiles

Configuration storage

Agent mode

Applying assets

Asset CRUD commands

Logging

Sending logs to Dash0

Querying logs from Dash0

Tracing

Sending spans to Dash0

Querying spans from Dash0

Getting a trace from Dash0

Metrics

Teams (experimental)

Members (experimental)

Raw HTTP passthrough (experimental)

Local OTLP proxy (experimental)

Common settings

Output formats

Shell completions

Contributing

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 31

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages