Command Reference

This document is a comprehensive reference for the dash0Copy CLI, aimed at enabling AI agents and automation workflows to use it effectively.

For every command, this reference lists the exact syntax, all flags, expected outputs, and concrete examples.

Command taxonomy

Every command falls into one of seven categories. Each category has distinct patterns for flags, output, and behavior.

Authentication commands populate or revoke the OAuth tokens of a profile. A profile can be in one of three auth states: static (holds a long-lived auth_*Copy token), OAuth-active (holds a dash0_at_*Copy access token and a refresh token; auto-refreshes), or OAuth-empty (marked as OAuth but not yet logged in). dash0 loginCopy requires an interactive terminal and never silently mutates a static profile. dash0 logoutCopy clears the OAuth tokens from a profile but keeps the profile shell for re-login.

Asset CRUD commands create, list, get, update, and delete dataset-scoped assets (dashboards, views, check rules, synthetic checks, recording rules). They use file-based input (-fCopy), support --dry-runCopy, and offer five output formats (tableCopy, wideCopy, jsonCopy, yamlCopy, csvCopy). The applyCopy command provides create-or-update semantics across all asset types.

Query commands search and retrieve telemetry signals. They accept time range flags (--fromCopy, --toCopy), a repeatable --filterCopy flag with the standard filter syntax, and customizable columns via --columnCopy. Output formats are tableCopy, jsonCopy, and csvCopy.

Send commands transmit telemetry data to Dash0 via OTLP. They require otlp-urlCopy (not api-urlCopy) and use repeatable attribute flags (--resource-attributeCopy, --scope-attributeCopy, and a signal-specific attribute flag).

Organizational commands manage entities (teams, members, notification channels) scoped to the organization, not to a dataset. They use flag-based input (no -fCopy, no --dry-runCopy, no applyCopy integration) and are all experimental. Notification channels are an exception: they use file-based input (-fCopy) and support --dry-runCopy, but are still organization-level (no --datasetCopy).

Raw HTTP command (apiCopy) is an escape hatch for endpoints that do not yet have a dedicated subcommand. It reuses the active profile's api-urlCopy, auth-tokenCopy, and (by default) datasetCopy, and emits a plain HTTP request. It is experimental.

Prerequisites

Every command that talks to the Dash0 API or OTLP endpoint needs credentials. The CLI resolves each individual setting (api-urlCopy, otlp-urlCopy, auth-tokenCopy, datasetCopy) in this order (first match wins):

1. Environment variables (DASH0_API_URLCopy, DASH0_OTLP_URLCopy, DASH0_AUTH_TOKENCopy, DASH0_DATASETCopy)
2. CLI flags (--api-urlCopy, --otlp-urlCopy, --auth-tokenCopy, --datasetCopy)
3. The selected profile (see below)

The profile itself is selected in this order (first match wins):

1. --profile <name>Copy flag
2. DASH0_PROFILECopy environment variable
3. The active profile recorded on disk (set via config profiles selectCopy, stored in ~/.dash0/Copy)

Using --profileCopy or DASH0_PROFILECopy does not modify the active profile on disk — it only changes which profile is read for the current invocation. Passing --profile ""Copy or DASH0_PROFILE=""Copy is treated as "not set" and falls through to the next step. If the selected profile does not exist, the command fails before making any API call with a message listing the available profile names.

Commands that read from the API (asset CRUD, logs queryCopy, spans queryCopy, traces getCopy, metrics instantCopy) require api-urlCopy and auth-tokenCopy. Commands that write via OTLP (logs sendCopy, spans sendCopy) require otlp-urlCopy and auth-tokenCopy.

Global flags

These flags are available on every command:

Agent mode

Agent mode optimizes the CLI for consumption by AI coding agents. When active, the CLI:

1. Defaults output format to JSON instead of tables.
2. Returns --helpCopy as structured JSON with flags, subcommands, and metadata.
3. Emits errors as JSON objects on stderr.
4. Skips confirmation prompts automatically (same as --forceCopy).
5. Disables colored output.

Agent mode is resolved in this priority order (first match wins):

1. DASH0_AGENT_MODE=0|falseCopy — explicitly disabled, overrides everything.
2. --agent-modeCopy flag — explicitly enabled.
3. DASH0_AGENT_MODE=1|trueCopy — explicitly enabled via environment variable.
4. Auto-detection via known AI agent environment variables: AIDERCopy, CLAUDE_CODECopy, CLAUDECODECopy, CLINECopy, CLINE_TASK_IDCopy, CODEXCopy, CURSOR_AGENTCopy, CURSOR_SESSION_IDCopy, GITHUB_COPILOTCopy, MCP_SESSION_IDCopy, OPENAI_CODEXCopy, WINDSURF_AGENTCopy, WINDSURF_SESSION_IDCopy.

Authentication

dash0 loginCopy and dash0 logoutCopy manage the OAuth tokens of a profile. Both commands operate on the active profile by default; pass --profile <name>Copy to target a specific one.

Profile auth states

A profile is in exactly one of three auth states:

OAuth-empty profiles cannot serve API calls — running a CLI command against one prints the active profile is OAuth-typed but not authenticated. Hint: Run \Copydash0 login` to log in.(orCopyprofile "" is OAuth-typed but not authenticated.whenCopy--profile` was passed).

In agent mode (--agent-modeCopy or DASH0_AGENT_MODE=1Copy), the hint is rewritten because dash0 loginCopy requires an interactive terminal. Agents are routed to two escape hatches: either set DASH0_AUTH_TOKENCopy to a static auth_*Copy token, or convert the profile back to static auth with dash0 config profiles update <name> --oauth=false --auth-token auth_<...> --forceCopy. The same agent-mode hint appears when an OAuth refresh fails at the API layer (token revoked or expired server-side).

loginCopy

Authenticate to Dash0 via OAuth 2.0 with PKCE. Opens the system browser, listens on a localhost TCP port for the callback, exchanges the authorization code for tokens, and saves them in the target profile.

1
dash0 login [--profile <name>] [--api-url <url>] [--port <n>] [--timeout <duration>]

State machine:

• OAuth-empty / OAuth-active target — proceeds silently. Re-login on an OAuth-active profile revokes the prior refresh token best-effort.
• Static target — prompts: <profile> uses a static auth token. Convert it to an OAuth profile (the existing auth token will be discarded)? [y/N]:Copy. Aborts cleanly on nCopy.
• No-auth target — prompts: <profile> has no auth token configured. Mark it as OAuth and log in? [y/N]:Copy. Aborts cleanly on nCopy.
• Missing target — prompts to create the profile as OAuth before proceeding.
• No active profile and no --profileCopy — fails immediately with a hint pointing at dash0 config profiles createCopy and dash0 login --profile <name>Copy.

The command requires an interactive terminal. In agent mode or when stdout is not a TTY, it exits with an error pointing at the static-token fallback (DASH0_AUTH_TOKENCopy or dash0 config profiles create --auth-tokenCopy).

Log in to the active profile:

12345
$ dash0 login
Opening your browser to log in to https://api.eu-west-1.aws.dash0.com
If the browser does not open automatically, paste this URL:
  https://api.eu-west-1.aws.dash0.com/oauth/authorize?...
Logged in as profile "prod" (access token expires in 1h0m0s).

Log in to a specific profile:

1
dash0 login --profile staging

Log in to a Dash0 region different from the active profile:

1
dash0 login --profile eu --api-url https://api.eu-west-1.aws.dash0.com

The OAuth client registration (RFC 7591) is cached per API URL in ~/.dash0/oauth-clients.jsonCopy, so re-running loginCopy against the same Dash0 region does not re-register a new client every time. The cache is invalidated automatically when the server reports invalid_clientCopy during token exchange.

OAuth access tokens are organization-scoped: each token is bound to whichever Dash0 organization the user picks during the browser consent step. Profiles for different organizations must each go through their own dash0 loginCopy.

logoutCopy

Clear the OAuth tokens of a profile and best-effort revoke them server-side. The profile shell is kept so a future dash0 loginCopy can re-fill it.

1
dash0 logout [--profile <name>] [--force]

Refuses to operate on static-token profiles and points the user at dash0 config profiles deleteCopy instead. Logging out of an OAuth-empty profile is a no-op and exits 0.

In agent mode (--agent-modeCopy or DASH0_AGENT_MODE=1Copy, also auto-detected from agent env vars like CLAUDE_CODECopy), logoutCopy requires an explicit --forceCopy and otherwise refuses with an error. This mirrors dash0 loginCopy's blanket refusal to run in agent mode: both directions of the OAuth session transition require deliberate user intent, so an AI agent invoking dash0 logoutCopy cannot silently revoke the refresh token of whichever profile the env points at.

Log out of the active profile:

123
$ dash0 logout
Log out of the active profile 'prod' (revoking its OAuth refresh token)? [y/N]: y
Logged out.

Log out of a named profile without confirmation:

12
$ dash0 logout --profile staging --force
Logged out of profile "staging".

[!NOTE] To leave OAuth behind entirely (not just log out), use dash0 config profiles update <name> --oauth=falseCopy. That clears the OAuth marker and lets the profile take a static token again.

Configuration

config profiles createCopy

Create a new named profile. All fields are optional at creation time. The first profile created becomes the active profile automatically.

123456
dash0 config profiles create <name> \
    [--api-url <url>] \
    [--otlp-url <url>] \
    [--auth-token <token>] \
    [--dataset <dataset>] \
    [--oauth]

Pass --oauthCopy to mark the profile as OAuth-authenticated. An OAuth profile is created in the OAuth-empty state — --api-urlCopy is required (so dash0 loginCopy knows where to authenticate), and --oauthCopy is mutually exclusive with --auth-tokenCopy. Run dash0 loginCopy afterwards to obtain the access and refresh tokens.

Example — static-token profile:

12345
$ 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
Profile "dev" added

Example — OAuth profile:

1234
$ dash0 config profiles create dev --oauth \
    --api-url https://api.us-west-2.aws.dash0.com
Profile "dev" created (OAuth).
Hint: Run `dash0 login` to authenticate.

Aliases: addCopy

config profiles updateCopy

Update an existing profile. Only the specified flags are changed; unspecified flags are left as-is. Pass an empty string to remove a field.

1234567
dash0 config profiles update <name> \
    [--api-url <url>] \
    [--otlp-url <url>] \
    [--auth-token <token>] \
    [--dataset <dataset>] \
    [--oauth[=true|=false]] \
    [--force]

--oauthCopy is the off-ramp for switching a profile between static and OAuth authentication. Both transitions are destructive and prompt for confirmation unless --forceCopy is set:

• --oauthCopy (or --oauth=trueCopy) on a static profile discards the existing static token and marks the profile as OAuth-empty (run dash0 loginCopy next).
• --oauth=falseCopy on an OAuth profile revokes its refresh token (best-effort) and clears the OAuth block. Pair it with --auth-token auth_<...>Copy to land in a static profile in one command; otherwise the profile is left token-less and dash0 config profiles updateCopy must be used again to set one.

--oauth=trueCopy and --auth-tokenCopy are mutually exclusive in the same invocation. Setting --auth-tokenCopy on an OAuth-active profile without also passing --oauth=falseCopy is rejected — the library cannot interpret a profile that holds both a static token and an OAuth block.

Update the API URL of a profile:

12
$ dash0 config profiles update prod --api-url https://api.us-east-1.aws.dash0.com
Profile "prod" updated

Convert a static-token profile to OAuth (prompts unless --forceCopy):

123
$ dash0 config profiles update prod --oauth --force
Profile "prod" updated
Hint: Run `dash0 login` to authenticate.

Convert an OAuth profile back to static in one command:

12
$ dash0 config profiles update prod --oauth=false --auth-token auth_xxx --force
Profile "prod" updated

Convert an OAuth profile back to no-auth (the user can set a token later):

123
$ dash0 config profiles update prod --oauth=false --force
Profile "prod" updated
Hint: This profile has no auth token configured. Set one with `dash0 config profiles update prod --auth-token auth_<...>`.

Remove a field by passing an empty string:

12
$ dash0 config profiles update prod --dataset ''
Profile "prod" updated

config profiles listCopy

List all profiles. The active profile is marked with *Copy in table output and with "active": trueCopy in JSON output.

1
dash0 config profiles list [-o <format>] [--skip-header]

Example output:

1234
  NAME  API URL                              OTLP URL                                    DATASET  AUTH
* dev   https://api.us-west-2.aws.dash0.com  https://ingress.us-west-2.aws.dash0.com     default  oauth ...dash0_at_xx (47m)
  prod  https://api.eu-west-1.aws.dash0.com  https://ingress.eu-west-1.aws.dash0.com     default  static ...uth_yyy
  cold  https://api.eu-west-1.aws.dash0.com                                              default  oauth (not logged in)

The AUTHCopy column carries the auth state per profile:

• static <masked-token>Copy for a profile with a long-lived auth_*Copy token.
• oauth <masked-token> (<remaining-lifetime>)Copy for an OAuth-active profile.
• oauth (not logged in)Copy for an OAuth-empty profile (created with --oauthCopy but dash0 loginCopy not yet run, or just logged out).
• (none)Copy when no token is configured.

JSON output keeps the existing authTokenCopy field and adds a sibling authKindCopy field with values staticCopy, oauth-activeCopy, oauth-emptyCopy, or noneCopy.

Use -o jsonCopy to get structured output (the default in agent mode):

1
$ dash0 config profiles list -o json

Use --skip-headerCopy to omit the header row from table output:

1
$ dash0 config profiles list --skip-header

Aliases: lsCopy

config profiles selectCopy

Set the active profile.

1
dash0 config profiles select <name>

Example:

12
$ dash0 config profiles select prod
Profile 'prod' is now active

Aliases: activateCopy

config profiles deleteCopy

Delete a profile.

1
dash0 config profiles delete <name>

Aliases: removeCopy

config showCopy

Display the resolved configuration (selected profile + environment variable overrides).

1
dash0 config show

Example output for a static-token profile:

12345
Profile:    prod
API URL:    https://api.eu-west-1.aws.dash0.com
OTLP URL:   https://ingress.eu-west-1.aws.dash0.com
Dataset:    default
Auth Token: ...uth_yyy

When the profile is OAuth, the Auth Token:Copy line is annotated:

12345
Profile:    dev
API URL:    https://api.us-west-2.aws.dash0.com
OTLP URL:   (not set)
Dataset:    default
Auth Token: ...dash0_at_xx    (OAuth, expires in 47m23s)

When the profile is OAuth but not yet logged in (OAuth-empty), the line points the user at dash0 loginCopy:

123456
Profile:    dev
API URL:    https://api.us-west-2.aws.dash0.com
OTLP URL:   (not set)
Dataset:    default
Auth Token: (OAuth, not logged in)
            Hint: Run `dash0 login` to authenticate.

The hint elides --profile <name>Copy when the displayed profile is already the active one.

-o jsonCopy (the default in agent mode) emits the same fields plus an oauthCopy object on OAuth profiles. For OAuth-active profiles the object contains clientIdCopy, expiresAtCopy (RFC 3339), and "authenticated": trueCopy. For OAuth-empty profiles the object contains "authenticated": falseCopy plus a hintCopy field naming the agent-mode recovery path (DASH0_AUTH_TOKENCopy or dash0 config profiles update <name> --oauth=false --auth-token auth_<...> --forceCopy). The oauthCopy object is omitted entirely when DASH0_AUTH_TOKENCopy is set, because the static token shadows the OAuth state.

12345678910
$ dash0 config show -o json
{
  "profile": {"value": "dev"},
  "apiUrl": {"value": "https://api.us-west-2.aws.dash0.com"},
  ...
  "oauth": {
    "authenticated": false,
    "hint": "set DASH0_AUTH_TOKEN to a static `auth_*` token, or convert the profile with `dash0 config profiles update dev --oauth=false --auth-token auth_<...> --force`"
  }
}

When an environment variable overrides a profile value, the output indicates the source:

123456
$ DASH0_API_URL='http://test' dash0 config show
Profile:    dev
API URL:    http://test    (from DASH0_API_URL environment variable)
OTLP URL:   https://ingress.us-west-2.aws.dash0.com
Dataset:    default
Auth Token: ...ULSzVkM

When a profile is selected via --profileCopy or DASH0_PROFILECopy, the Profile:Copy line is annotated with the source:

1234567
$ dash0 --profile prod config show
Profile:    prod    (from --profile flag)
...

$ DASH0_PROFILE=prod dash0 config show
Profile:    prod    (from DASH0_PROFILE environment variable)
...

Asset CRUD commands

Asset CRUD commands create, list, get, update, and delete Dash0 assets. Dash0 calls dashboards, views, synthetic checks, and check rules "assets" (not "resources", which is an overloaded term in OpenTelemetry).

All seven asset types (dashboardsCopy, check-rulesCopy, synthetic-checksCopy, viewsCopy, recording-rulesCopy, notification-channelsCopy, spam-filtersCopy) share the same CRUD subcommands. The examples below use dashboardsCopy, but the same patterns apply to every asset type.

listCopy

List all assets in the dataset.

1
dash0 dashboards list [--limit <n>] [-o <format>] [--skip-header]

Example:

12345
$ dash0 dashboards list
NAME                                      ID
Production Overview                       a1b2c3d4-5678-90ab-cdef-1234567890ab
Staging Overview                          d4e5f6a7-8901-23de-f012-4567890abcde
...

The wideCopy format adds DATASETCopy, ORIGINCopy, and URLCopy columns:

123
$ dash0 dashboards list -o wide
NAME                  ID                                    DATASET   ORIGIN       URL
Production Overview   a1b2c3d4-5678-90ab-cdef-1234567890ab  default   gitops/prod  https://app.dash0.com/goto/dashboards?dashboard_id=a1b2c3d4-...

Use -o jsonCopy or -o yamlCopy to get the full asset definitions, suitable for backup or re-applying with apply -f -Copy. The YAML output is a multi-document stream (documents separated by ---Copy) so it can be piped directly to dash0 apply -f -Copy. Use -o csvCopy for a pipe-friendly, machine-readable format with the same columns as wideCopy:

123
$ dash0 dashboards list -o csv
name,id,dataset,origin,url
Production Overview,a1b2c3d4-5678-90ab-cdef-1234567890ab,default,gitops/prod,https://app.dash0.com/goto/dashboards?dashboard_id=a1b2c3d4-...

Aliases: lsCopy

getCopy

Retrieve a single asset by ID.

1
dash0 dashboards get <id> [-o <format>]

Example (default table output):

12345678
$ dash0 dashboards get a1b2c3d4-5678-90ab-cdef-1234567890ab
Kind: Dashboard
Name: Production Overview
Dataset: default
Origin: gitops/prod
URL: https://app.dash0.com/goto/dashboards?dashboard_id=a1b2c3d4-5678-90ab-cdef-1234567890ab
Created: 2026-01-15 10:30:00
Updated: 2026-01-20 14:45:00

Use -o yamlCopy to get the full definition, suitable for editing and re-applying:

123456789
$ dash0 dashboards get a1b2c3d4-5678-90ab-cdef-1234567890ab -o yaml
kind: Dashboard
metadata:
  name: a1b2c3d4-5678-90ab-cdef-1234567890ab
  ...
spec:
  display:
    name: Production Overview
  ...

createCopy

Create a new asset from a YAML or JSON file.

1
dash0 dashboards create -f <file> [--dry-run] [-o <format>]

Use -f -Copy to read from stdin. The --dry-runCopy flag validates the file without creating anything.

Example:

12
$ dash0 dashboards create -f dashboard.yaml
Dashboard "My Dashboard" created

dashboards createCopy also accepts PersesDashboard CRD files (perses.dev/v1alpha1Copy and perses.dev/v1alpha2Copy).

12
$ dash0 dashboards create -f persesdashboard.yaml
Dashboard "My Perses Dashboard" created

check-rules createCopy also accepts PrometheusRule CRD files. Each alerting rule in the CRD is created as a separate check rule (recording rules are skipped). The check rule name is composed as <group name> - <alert name>Copy, matching the name produced by the Dash0 Kubernetes operator and the Terraform provider for the same CRD:

12
$ dash0 check-rules create -f prometheus-rules.yaml
Check rule "High Error Rate Alert" created

Aliases: addCopy

updateCopy

Update an existing asset from a YAML or JSON file. If the ID argument is omitted, the ID is extracted from the file content. The output shows a unified diff of what changed. The --dry-runCopy flag shows the diff without applying the update.

1
dash0 dashboards update [id] -f <file> [--dry-run]

Update a dashboard from a file:

12345678
$ dash0 dashboards update <id> -f dashboard.yaml
--- Dashboard (before)
+++ Dashboard (after)
@@ -2,7 +2,7 @@
 spec:
   display:
-    name: Old Dashboard Name
+    name: New Dashboard Name

Preview changes without applying:

12345678
$ dash0 dashboards update -f dashboard.yaml --dry-run
--- Dashboard (before)
+++ Dashboard (after)
@@ -2,7 +2,7 @@
 spec:
   display:
-    name: Old Dashboard Name
+    name: New Dashboard Name

When nothing changed:

12
$ dash0 dashboards update -f dashboard.yaml
Dashboard "My Dashboard": no changes

deleteCopy

Delete an asset by ID. Prompts for confirmation unless --forceCopy is passed.

1
dash0 dashboards delete <id> [--force]

Interactive deletion (prompts for confirmation):

123
$ dash0 dashboards delete a1b2c3d4-5678-90ab-cdef-1234567890ab
Are you sure you want to delete dashboard "a1b2c3d4-..."? [y/N]: y
Dashboard "a1b2c3d4-..." deleted

Non-interactive deletion (--forceCopy skips the prompt):

12
$ dash0 dashboards delete a1b2c3d4-5678-90ab-cdef-1234567890ab --force
Dashboard "a1b2c3d4-..." deleted

Aliases: removeCopy

Asset type quick reference

Asset identifiers and idempotent upsert

Every asset type accepts a user-defined identifier in its YAML/JSON document. When the identifier is present, both createCopy and applyCopy perform an upsert (PUT) against that identifier: the asset is created on the first call and replaced on every subsequent call. When the identifier is absent, both commands perform a plain create (POST) and the server assigns a fresh ID on each invocation — repeated runs produce duplicate assets.

Pinning a stable identifier in the source document is the supported way to make applyCopy and createCopy idempotent, which is what GitOps and CI/CD workflows need.

The identifier field location varies by asset kind:

The dash0.com/idCopy label is the user-defined external identifier and is distinct from dash0.com/originCopy, which records the system of record (dash0-cliCopy, terraformCopy, uiCopy). The CLI strips dash0.com/originCopy from outbound payloads for the asset types where the server treats origin as provenance metadata (dashboards, views, check rules, synthetic checks), so do not use origin as the upsert key for those kinds. Notification channels and spam filters are the two exceptions: their server APIs key on origin, and the CLI preserves it accordingly.

When list -o yamlCopy or get -o yamlCopy exports an existing asset, the server-assigned ID is rendered into the correct field, so the export-edit-reapply workflow round-trips through the identifier automatically.

applyCopy

Apply asset definitions from a file, directory, or stdin. If an asset already exists (matched by ID), it is updated; otherwise it is created.

1
dash0 apply -f <file|directory> [--dry-run]

For assets that are updated, a unified diff of the changes is shown. Assets that are created show the standard creation message.

When a directory is specified, all .yamlCopy and .ymlCopy files are discovered recursively. Hidden files and directories (starting with .Copy) are skipped. All documents are validated before any are applied. If any document fails validation, no changes are made.

Supported kindCopy values: DashboardCopy, PersesDashboardCopy, CheckRuleCopy, PrometheusRuleCopy, SyntheticCheckCopy, ViewCopy, Dash0SpamFilterCopy, Dash0NotificationChannelCopy. A single file may contain multiple documents separated by ---Copy.

For Dash0SpamFilterCopy, the apiVersionCopy field on the document selects the schema (v1alpha1Copy or v1alpha2Copy); a missing value defaults to v1alpha1Copy. An unknown value fails validation up front, before any document is applied.

For PrometheusRuleCopy, applyCopy inspects each rule entry and dispatches by type. Alerting rules (entries with alert:Copy) are sent to the check-rule endpoint as one check rule per alert, named <group name> - <alert name>Copy to match the Dash0 Kubernetes operator and the Terraform provider. Recording rules (entries with record:Copy) are sent to the recording-rule endpoint as a single PrometheusRule CRD with the alerting rules removed. A CRD that mixes both kinds is dispatched to both endpoints in a single apply. A CRD that contains no alerting and no recording rules fails validation up front.

Dash0NotificationChannelCopy documents are dispatched to the organization-level notification-channels endpoint and are not associated with a dataset. The dash0.com/originCopy label is the upsert key when present; otherwise the server assigns a fresh ID on each apply.

[!NOTE] The -fCopy flag accepts a single path. Do not use shell glob patterns like -f assets/*Copy — the shell expands the glob into multiple arguments and only the first file is passed to -fCopy. Use -f assets/Copy (the directory) instead.

Apply a single file:

12
$ dash0 apply -f dashboard.yaml
Dashboard "Production Overview" (a1b2c3d4-...) created

Apply a directory recursively:

1234
$ dash0 apply -f assets/
assets/dashboard.yaml: Dashboard "Production Overview" (a1b2c3d4-...) created
assets/rule.yaml: Check rule "High Error Rate" (b2c3d4e5-...) updated
...

Apply from stdin (the cat … | dash0 apply -f -Copy pipeline counts as one command):

123
$ cat assets.yaml | dash0 apply -f -
Dashboard "Production Overview" (a1b2c3d4-...) created
...

Dry-run validation:

123
$ dash0 apply -f assets.yaml --dry-run
Dry run: 1 document validated
  1. Dashboard "Production Overview" (a1b2c3d4-5678-90ab-cdef-1234567890ab)

Asset YAML formats

Dashboard:

12345678
kind: Dashboard
metadata:
  name: a1b2c3d4-5678-90ab-cdef-1234567890ab
  dash0Extensions:
    id: a1b2c3d4-5678-90ab-cdef-1234567890ab
spec:
  display:
    name: Production Overview

The user-defined identifier lives in metadata.dash0Extensions.idCopy (see asset identifiers). metadata.nameCopy is the CRD-style metadata name and is independent of spec.display.nameCopy, which is the title shown in the UI. Omitting dash0Extensions.idCopy causes every createCopy / applyCopy to allocate a new server-assigned ID, breaking idempotency.

PersesDashboard (Perses CRD, converted to a Dashboard on import):

1234567891011
apiVersion: perses.dev/v1alpha1
kind: PersesDashboard
metadata:
  name: my-perses-dashboard
  labels:
    dash0.com/id: a1b2c3d4-5678-90ab-cdef-1234567890ab
spec:
  display:
    name: My Perses Dashboard
  duration: 5m
  panels: {}

For PersesDashboards the user-defined identifier is the dash0.com/idCopy metadata label (see asset identifiers).

Check rule:

1234
kind: CheckRule
id: b2c3d4e5-6789-01bc-def0-234567890abc
name: High Error Rate
expression: sum(rate(http_requests_total{status=~"5.."}[5m])) > 0.1

View:

1234567
kind: View
metadata:
  name: Error Logs
  labels:
    dash0.com/id: c3d4e5f6-7890-12cd-ef01-34567890abcd
spec:
  query: "severity >= ERROR"

Synthetic check:

12345678
kind: SyntheticCheck
metadata:
  name: API Health Check
  labels:
    dash0.com/id: d4e5f6a7-8901-23de-f012-4567890abcde
spec:
  url: https://api.example.com/health
  interval: 60s

Recording rule (PrometheusRule CRD format):

12345678910111213
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: My Recording Rules
  labels:
    dash0.com/id: e5f6a7b8-9012-34ef-0123-567890abcdef
spec:
  groups:
    - name: cpu-averages
      interval: 1m
      rules:
        - record: instance:cpu_usage:avg5m
          expr: avg without(cpu) (rate(node_cpu_seconds_total{mode!="idle"}[5m]))

Spam filter (v1alpha1 — spec.contextsCopy is an array of signal types):

1234567891011121314
apiVersion: v1alpha1
kind: Dash0SpamFilter
metadata:
  name: Drop noisy health checks
  labels:
    dash0.com/id: a6b7c8d9-0123-45a6-7890-cdef01234567
spec:
  contexts:
    - log
    - span
  filter:
    - key: http.target
      operator: ends_with
      value: /healthz

Spam filter (v1alpha2 — spec.contextCopy is a single signal type):

123456789101112
apiVersion: v1alpha2
kind: Dash0SpamFilter
metadata:
  name: Drop debug logs
  labels:
    dash0.com/id: b7c8d9e0-1234-56b7-8901-def012345678
spec:
  context: log
  filter:
    - key: otel.log.severity.range
      operator: is
      value: DEBUG

The CLI detects the apiVersion from the document and routes to the corresponding endpoint. The listCopy endpoint returns v1alpha1 definitions only; use spam-filters get <id>Copy to retrieve a filter in its native apiVersion. The deleteCopy endpoint is version-agnostic.

Notification channel (organization-level, no --datasetCopy):

123456789
kind: Dash0NotificationChannel
metadata:
  name: Slack Alerts
  labels:
    dash0.com/origin: my-slack-channel
spec:
  type: slack
  config:
    url: https://hooks.slack.com/services/T00/B00/XXX

Mixed PrometheusRule (one alerting rule and one recording rule in the same CRD):

123456789101112131415161718
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: Mixed Rules
  labels:
    dash0.com/id: c8d9e0f1-2345-67c8-9012-ef0123456789
spec:
  groups:
    - name: errors-and-cpu
      interval: 1m
      rules:
        - alert: HighErrorRate
          expr: sum(rate(errors[5m])) > 0.1
          for: 5m
          labels:
            severity: critical
        - record: instance:cpu_usage:avg5m
          expr: avg without(cpu) (rate(node_cpu_seconds_total{mode!="idle"}[5m]))

The alerting rule is created as a check rule under /api/alerting/check-rulesCopy, and a recording-rule CRD with only the recording rule is created under /api/recording-rulesCopy.

Multi-document file (separated by ---Copy):

1234567891011
kind: Dashboard
metadata:
  name: e1f2a3b4-5678-90e5-6789-abcdef012345
spec:
  display:
    name: First Dashboard
---
kind: CheckRule
id: f2a3b4c5-6789-01f6-7890-bcdef0123456
name: Second Document Rule
expression: up == 0

Query commands

Query commands search and retrieve telemetry signals and alerting issues from Dash0. They share a common set of characteristics:

• Time range flags: --fromCopy and --toCopy (relative expressions like now-1hCopy or absolute ISO 8601 timestamps).
• Filter flag: --filterCopy with the standard key [operator] valueCopy syntax (see filter syntax).
• Column flag: --columnCopy for customizing table/CSV output (see custom columns).
• Pagination: --limitCopy.
• Output formats: tableCopy, jsonCopy, csvCopy (no wideCopy or yamlCopy).
• Sampling flag: --precisionCopy to disable adaptive sampling on logs queryCopy and spans queryCopy (traces getCopy always disables it; metrics instantCopy and failed-checks queryCopy do not honor it).

logs queryCopy

Query log records from Dash0. Requires api-urlCopy and auth-tokenCopy.

1
dash0 logs query [flags]

Both --fromCopy and --toCopy accept relative expressions like now-1hCopy or absolute ISO 8601 timestamps. Absolute timestamps are normalized to millisecond precision, so 2024-01-25T10:00:00ZCopy and 2024-01-25Copy are both accepted.

Query recent logs (last 15 minutes, up to 50 records):

12345
$ dash0 logs query
TIMESTAMP                     SEVERITY    BODY
2026-02-16T09:12:03.456Z      INFO        Application started successfully
2026-02-16T09:12:04.789Z      ERROR       Connection timeout
...

Query with a time range:

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

Filter by service:

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

Filter by severity (errors and above):

1
dash0 logs query --filter "otel.log.severity.number gte 17"

Multiple filters (AND logic):

123
dash0 logs query \
    --filter "service.name is my-service" \
    --filter "otel.log.severity.range is_one_of ERROR WARN"

Use JSON filter criteria copied from the Dash0 UI:

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

Output as JSON (full OTLP payload):

1
dash0 logs query -o json

Output as CSV (pipe-friendly):

1234
$ dash0 logs query -o csv
otel.log.time,otel.log.severity.range,otel.log.body
2026-02-16T09:12:03.456Z,INFO,Application started successfully
...

CSV without header:

1
dash0 logs query -o csv --skip-header

Disable adaptive sampling so a narrow filter always returns every match:

1
$ dash0 logs query --precision disabled --filter "test.id is <id>"

spans queryCopy

Query spans from Dash0. Requires api-urlCopy and auth-tokenCopy.

1
dash0 spans query [flags]

Both --fromCopy and --toCopy accept relative expressions like now-1hCopy or absolute ISO 8601 timestamps.

Query recent spans (last 15 minutes, up to 50 spans):

12345
$ dash0 spans query
TIMESTAMP                     DURATION    SPAN NAME                                 STATUS    SERVICE NAME                    PARENT ID         TRACE ID                          SPAN LINKS
2026-02-16T09:12:03.456Z      150ms       GET /api/users                            OK        my-service                                        0af76519...
2026-02-16T09:12:04.789Z      500ms       POST /api/orders                          ERROR     api-gateway                     b7ad6b7169203331  3d3d3d3d...
...

Query with a time range:

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

Filter by service:

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

Filter by span status:

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

Use JSON filter criteria copied from the Dash0 UI:

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

Output as CSV:

1234
$ dash0 spans query -o csv
otel.span.start_time,otel.span.duration,otel.span.name,otel.span.status.code,service.name,otel.parent.id,otel.trace.id,otel.span.links
2026-02-16T09:12:03.456Z,150ms,GET /api/users,OK,my-service,,0af76519...,
...

Output as OTLP JSON:

1
dash0 spans query -o json --limit 10

The --filterCopy flag uses the same filter syntax as logs queryCopy. Common span attribute keys: service.nameCopy, otel.span.status.codeCopy, otel.trace.idCopy, otel.span.nameCopy.

traces getCopy

Retrieve all spans belonging to a trace from Dash0. Requires api-urlCopy and auth-tokenCopy.

traces getCopy always disables adaptive sampling so every span in the trace is returned. The command does not accept the --precisionCopy flag.

1
dash0 traces get <trace-id> [flags]

The <trace-id>Copy argument must be 32 hex characters.

In table format, spans are displayed as a hierarchical tree with child spans indented under their parents.

Get all spans in a trace:

12345
$ dash0 traces get <trace-id>
TIMESTAMP                     DURATION    TRACE ID                          SPAN ID           PARENT ID         SPAN NAME                                   STATUS    SERVICE NAME                    SPAN LINKS
2026-02-16T09:12:03.456Z      200ms       0af7651916cd43dd8448eb211c80319c  b7ad6b7169203331                    GET /api/users                              OK        frontend
2026-02-16T09:12:03.486Z      150ms       0af7651916cd43dd8448eb211c80319c  00f067aa0ba902b7  b7ad6b7169203331  SELECT * FROM users                         UNSET     frontend
2026-02-16T09:12:03.641Z      10ms        0af7651916cd43dd8448eb211c80319c  123456789abcdef0  b7ad6b7169203331  serialize response                          UNSET     frontend

Get a trace with a specific time range:

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

Follow span links to related traces:

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

Follow span links with a custom lookback period:

1
dash0 traces get <trace-id> --follow-span-links 2h

Output as OTLP JSON:

1
dash0 traces get <trace-id> -o json

Output as CSV:

1234
$ dash0 traces get <trace-id> -o csv
otel.trace.id,otel.span.start_time,otel.span.duration,otel.span.id,otel.parent.id,otel.span.name,otel.span.status.code,service.name,otel.span.links
0af7651916cd43dd8448eb211c80319c,2026-02-16T09:12:03.456Z,200ms,b7ad6b7169203331,,GET /api/users,OK,frontend,
...

When --follow-span-linksCopy is used, linked traces are displayed after the primary trace, separated by a header line showing the linked trace ID. The command follows links recursively up to a maximum of 20 traces.

metrics instantCopy

Run an instant PromQL query against the Dash0 API, returning a single datapoint per time series.

With a raw PromQL expression:

1
dash0 metrics instant --promql <promql> [--from <timestamp>] [--dataset <dataset>] [-o <format>]

With one or more --filterCopy expressions (translated to PromQL label matchers):

1
dash0 metrics instant --filter <filter> [--from <timestamp>] [--dataset <dataset>] [-o <format>]

At least one of --promqlCopy or --filterCopy must be specified.

The --queryCopy flag (alias for --promqlCopy) and --timeCopy flag (alias for --fromCopy) are deprecated but still accepted for backwards compatibility.

Output formats

The default tableCopy output uses a verbose label-per-line format showing all labels for each metric result. Use --columnCopy to switch to a columnar table format with specific columns.

The csvCopy output defaults to columns: timestampCopy, __name__Copy, valueCopy. Use --columnCopy to override the default columns.

When no --columnCopy is specified, a hint listing the available label keys is printed to stderr.

The --columnCopy flag accepts any Prometheus label key from the result (e.g., __name__Copy, service_nameCopy, jobCopy, instanceCopy). Built-in columns timestampCopy and valueCopy are always available. The --columnCopy flag is not supported with -o jsonCopy.

[!NOTE] The column otel_metric_nameCopy is not available in Prometheus query results. Use __name__Copy for the Prometheus-normalized metric name.

Filter syntax

The --filterCopy flag uses the same filter syntax as logs queryCopy. Filters are translated to PromQL label matchers. For example, --filter "service.name is my-service"Copy becomes {service_name="my-service"}Copy.

OTel attribute keys are normalized to Prometheus label names (dots replaced with underscores).

Examples

Query the current request rate per service:

1
dash0 metrics instant --promql 'sum by (service_name) (rate(http_server_request_duration_seconds_count[5m]))'

Query against a specific dataset:

1
dash0 metrics instant --promql 'sum(rate(http_server_request_duration_seconds_count[5m]))' --dataset production

Query at a specific evaluation time:

1
dash0 metrics instant --promql 'sum by (service_name) (rate(http_server_request_duration_seconds_count[5m]))' --from 2024-01-25T10:00:00Z

Query with filters instead of PromQL:

1
dash0 metrics instant --filter 'service.name is my-service'

Output as CSV:

1
dash0 metrics instant --promql 'sum by (service_name) (rate(http_server_request_duration_seconds_count[5m]))' -o csv

Output as CSV without header:

1
dash0 metrics instant --promql 'sum by (service_name) (rate(http_server_request_duration_seconds_count[5m]))' -o csv --skip-header

Select specific columns:

1
dash0 metrics instant --promql 'sum by (service_name) (rate(http_server_request_duration_seconds_count[5m]))' --column value --column service_name

Output as JSON:

1
dash0 metrics instant --promql 'sum by (service_name) (rate(http_server_request_duration_seconds_count[5m]))' -o json

failed-checks queryCopy

Query failed check instances (active or recently resolved issues raised by check rules) from Dash0 alerting. Requires api-urlCopy and auth-tokenCopy.

1
dash0 failed-checks query [flags]

The --statusCopy and --activeCopy flags are convenience shortcuts that translate into the equivalent --filterCopy expressions on the well-known issue attributes the alerting API exposes (dash0.issue.statusCopy and dash0.issue.end_timeCopy). Custom labels — for example a team-defined priorityCopy or ownerCopy label — must be filtered through --filterCopy.

Aliases: listCopy, lsCopy.

List currently active (unresolved) issues:

1234
$ dash0 failed-checks query --active
CHECK RULE                                     STATUS      STARTED              SUMMARY
BLOCK DEPLOYMENTS - please update reason ...   critical    2026-06-19 13:10:54  BLOCK DEPLOYMENTS due to XYZ
...

Filter by instance status:

1
dash0 failed-checks query --status critical,degraded

Filter by an arbitrary issue label (priorityCopy, ownerCopy, or any other label set on the originating check rule):

1
dash0 failed-checks query --filter "priority is_one_of p1 p2" --active

Issues from the last hour (active and resolved):

1
dash0 failed-checks query --filter "priority is p1" --from now-1h

Use JSON filter criteria copied from the Dash0 UI:

12
dash0 failed-checks query \
    --filter '[{"key":"priority","operator":"is","value":"p1"}]'

Output as JSON:

1
dash0 failed-checks query --active -o json

Output as CSV:

1234
$ dash0 failed-checks query --status critical --active -o csv
dash0.issue.check_rule_name,dash0.issue.status,dash0.issue.start_time,dash0.issue.summary
BLOCK DEPLOYMENTS - please update reason ...,critical,2026-06-19 13:10:54,BLOCK DEPLOYMENTS due to XYZ
...

Show only specific columns:

12
dash0 failed-checks query \
    --column "check rule" --column status --column summary

Any issue label key (for example priorityCopy or ownerCopy) can be used directly as a column name. Add a PRIORITYCopy column derived from the priorityCopy issue label:

1234
$ dash0 failed-checks query --active --column "check rule" --column priority --column status --column summary
CHECK RULE                                     priority  STATUS      SUMMARY
BLOCK DEPLOYMENTS - please update reason ...   p1        critical    BLOCK DEPLOYMENTS due to XYZ
...

The header for a label-based column defaults to the label key as-is. To override it, combine --columnCopy with --skip-headerCopy and render the header separately, or use the JSON output and post-process.

Column aliases (case-insensitive): check ruleCopy/ruleCopy → dash0.issue.check_rule_nameCopy, statusCopy → dash0.issue.statusCopy, startedCopy/startCopy → dash0.issue.start_timeCopy, endedCopy/endCopy → dash0.issue.end_timeCopy, summaryCopy → dash0.issue.summaryCopy, descriptionCopy → dash0.issue.descriptionCopy, idCopy → dash0.issue.idCopy, identifierCopy → dash0.issue.identifierCopy, check rule idCopy/rule idCopy → dash0.issue.check_rule_idCopy.

Filter syntax

The --filterCopy flag accepts expressions in the form key [operator] valueCopy. When the operator is omitted, isCopy (exact match) is assumed.

The flag also accepts JSON filter criteria as produced by the Dash0 UI "copy filter criteria" feature. A JSON array of filter objects is expanded into multiple filters; a single JSON object is treated as one filter. For example:

12345
# Paste a JSON array copied from the Dash0 UI
$ dash0 logs query --filter '[
  {"key": "service.name", "operator": "is", "value": "api"},
  {"key": "otel.log.severity.range", "operator": "is_one_of", "values": ["ERROR", "WARN"]}
]'

JSON filters and text filters can be mixed freely across multiple --filterCopy flags.

Keys containing spaces can be single-quoted: 'my key' is valueCopy. Values containing spaces can be single-quoted: deployment.environment.name is_one_of 'us east' 'eu west' stagingCopy.

Common log attribute keys: service.nameCopy, otel.log.severity.numberCopy, otel.log.severity.rangeCopy, otel.log.severity.textCopy, otel.log.bodyCopy. Valid values for otel.log.severity.rangeCopy: TRACECopy, DEBUGCopy, INFOCopy, WARNCopy, ERRORCopy, FATALCopy, UNKNOWNCopy.

Precision mode (adaptive sampling)

By default the Dash0 API applies adaptive sampling to log and span queries. The sampler intelligently samples telemetry data during query execution to keep queries fast on large datasets, while returning statistically representative results. All telemetry data is stored and available; adaptive sampling only affects how queries are executed, not what data is kept.

The representative-but-incomplete trade-off is fine for exploration, but for narrow lookups that expect every match — scripted lookups by trace ID, request ID, or any other near-unique attribute — a single matching log or span can be omitted from the response.

Pass --precision disabledCopy to logs queryCopy or spans queryCopy to switch the request to Precision mode, the API equivalent of the Precision toggle in the Dash0 UI. Precision mode keeps queries deterministic at the cost of higher latency on large windows.

The flag accepts either value of the API's sampling mode:

• --precision disabledCopy — disable adaptive sampling and return every match.
• --precision adaptiveCopy — explicit form of the default; useful when overriding a profile or environment-set default in scripts.

When the flag is omitted, the request leaves the sampling field unset and the server applies its default (currently adaptiveCopy).

12
# Narrow lookup: always return every matching log
dash0 logs query --precision disabled --filter "test.id is <id>"

12
# Narrow lookup: always return every matching span
dash0 spans query --precision disabled --filter "test.id is <id>"

traces getCopy does not accept --precisionCopy — it always disables adaptive sampling so the complete trace, including any spans that would otherwise be sampled out, is returned.

The flag is not available on metrics instantCopy: the Prometheus-compatible API the command uses does not honor the sampling field.

Custom columns

The --columnCopy flag lets you choose which columns appear in tableCopy and csvCopy output. It is repeatable: pass one --columnCopy per column. When used, the flag replaces the default column set entirely.

Show only timestamp and body:

1
dash0 logs query --column time --column body

Include an arbitrary attribute column:

123
dash0 spans query \
    --column timestamp --column duration \
    --column "span name" --column http.request.method

Include an arbitrary attribute column by key:

1
dash0 logs query --column time --column service.name --column body

Each command has predefined columns with short aliases. Aliases are matched case-insensitively. Any OTLP attribute key (resource, scope, or record/span level) can also be used as a column; its header defaults to the attribute key as-is.

Log query aliases:

Span query aliases:

Trace get aliases share the span query aliases.

Failed-checks query aliases:

Any issue label key (e.g. priorityCopy, ownerCopy, or any custom label set on the originating check rule) can be used directly as a column name. For example, --column priorityCopy renders a column whose values come from the priorityCopy issue label.

Aliases that contain spaces must be quoted: --column "start time"Copy.

The --columnCopy flag is not supported with JSON output. Using --columnCopy with -o jsonCopy returns an error.

Send commands

Send commands transmit telemetry data to Dash0 via OTLP. They share a common set of characteristics:

• Require otlp-urlCopy and auth-tokenCopy (not api-urlCopy).
• Repeatable attribute flags: --resource-attributeCopy, --scope-attributeCopy, and a signal-specific attribute flag.
• OTLP scope flags: --scope-nameCopy (default: dash0-cliCopy), --scope-versionCopy (default: CLI version).