Osuite CLI reference

The osuite CLI queries your telemetry — logs, metrics, and traces — and manages dashboards as code from the terminal. It is the same tool the Osuite AI agents drive under the hood, so anything an agent can read or change, you can script directly.

This page documents every command. For first-time install and authentication, follow Set up the Osuite AI agents — the CLI setup is shared with the agents and is not repeated here.

Install

The CLI is published to npm as @osuite/cli and installs globally.

npm install @osuite/cli -g

Confirm the install and check the version.

osuite --version

Authenticate

The CLI reads two environment variables. Both are required; the CLI exits with an error if either is missing.

Variable	Purpose
OSUITE_API_KEY	Your Osuite API key. Sent as a bearer token on every request.
OSUITE_API_ENDPOINT	Your region’s query API base URL, for example https://api.<region>.osuite.io.

Add them to your shell profile:

export OSUITE_API_ENDPOINT=https://api.<region>.osuite.io
export OSUITE_API_KEY=<your-api-key>

Run osuite whoami to confirm you are authenticated. Create an API key in the Osuite UI under Settings → API Keys — see Set up the Osuite AI agents for the full walkthrough.

The API endpoint used here is the query API, which is different from the OTLP ingest endpoint your services send telemetry to. See the OTLP endpoints reference for the distinction.

Global options

These apply to osuite itself and are available on every command.

Option	Description
-o, --output <format>	Output format: json or text. Defaults vary by command (see below).
-V, --version	Print the CLI version.
-h, --help	Print help for the CLI or any command. Run osuite <command> --help for a specific command.

Default output formats:

Command group	Default --output
logs, traces	json
metrics, whoami	json
dashboard	text

text output prints a human-readable summary with progress spinners; json prints the raw structured response, suitable for piping into jq or another tool.

Commands

Command	What it does
dashboard	Manage dashboards as code — pull, plan, and apply local JSON files.
logs	Search logs, Kubernetes events, and RUM session events.
metrics	Run PromQL queries and discover metrics and labels.
traces	Search distributed traces and individual spans.
whoami	Print the authenticated user profile.
init-ai	Install the Osuite AI agent skills globally.
upgrade	Upgrade the CLI and refresh the installed skills.

Filter syntax

The logs and traces search commands share a filter grammar. Each --filter takes an expression in the form field__operator=value, and you can pass --filter multiple times to combine conditions.

Operator	Meaning	Example
is	Exact match	resource.service.name__is=checkout
is_not	Exclude match	resource.service.environment__is_not=dev
in	One of a comma-separated list	severity.text__in=error,warning
contains	Substring match (traces only)	operationName__contains=http
gt, gte, lt, lte	Numeric comparisons	duration__gt=1000

Field names are the fully qualified attribute paths Osuite stores, such as resource.service.name or attributes.event.name. See the resource attributes reference for the common resource fields and how they map to the UI.

Time ranges

The query commands accept a relative range or an explicit start and end.

• --range <range> — one of 15m, 1h, 6h, 1d, 4d.
• --start / --end — an explicit window that overrides --range.

The unit of --start and --end differs by command:

• logs and traces take milliseconds since the epoch.
• metrics query takes seconds since the epoch.

dashboard

Manage Osuite dashboards as code. Local JSON files are the source of truth: you pull dashboards down, edit them, preview the diff, and apply the changes back. For the dashboard file format, see the dashboard JSON schema reference.

osuite dashboard <subcommand> [path]

Subcommand	Description
pull	Pull all dashboards from Osuite into the current directory as JSON files.
plan [path]	Preview the changes that apply would make, without calling the API to mutate anything.
apply [path]	Apply local dashboard JSON files to Osuite.

dashboard apply

apply mutates remote state from your local .json files:

• A dashboard with no id (or an id not found remotely) is created, and the returned id is written back to the local file.
• A dashboard with an existing id is updated.
• A dashboard with no changes is skipped.

If [path] is omitted, every *.json file in the current directory is used. Pass a file or a directory to narrow the set.

Option	Description
--dry-run	Preview changes without making API calls.

osuite dashboard apply
osuite dashboard apply ./dashboards/
osuite dashboard apply my-dashboard.json
osuite dashboard apply --dry-run

Run osuite dashboard plan or apply --dry-run first to review the diff before writing to your account.

logs

Query logs and event streams from Osuite. All three subcommands share the filter syntax and time-range options.

Subcommand	Description
search	Search application and infrastructure logs.
k8s-events	Search Kubernetes cluster events.
session-events	Search RUM session events.

Common options for all three:

Option	Description
--filter <filters...>	One or more field__operator=value expressions.
--limit <n>	Maximum results to return (default 100).
--range <range>	Relative time range (default 1h).
--start <ms>	Start time in milliseconds since the epoch (overrides --range).
--end <ms>	End time in milliseconds since the epoch (overrides --range).

logs search

osuite logs search --filter resource.service.name__is=myservice
osuite logs search --filter severity.text__in=error,warning --filter resource.service.environment__is_not=dev
osuite logs search --range 6h
osuite logs search --start 1710460800000 --end 1710547200000 --output json

logs k8s-events

Search cluster events collected by the osuite-k8s Helm chart. Common fields include resource.cluster, resource.environment, resource.k8s.namespace.name, attributes.event.domain, and attributes.event.name.

osuite logs k8s-events --filter resource.k8s.namespace.name__is=observability
osuite logs k8s-events --filter resource.cluster__is=osuite-us-east-1 --filter resource.environment__is=prod-us
osuite logs k8s-events --range 1d --limit 50 --output json

logs session-events

Search RUM session events. Common fields include resource.cluster, resource.environment, attributes.event.domain, and attributes.event.name.

osuite logs session-events --filter attributes.event.domain__is=session
osuite logs session-events --filter resource.environment__is=prod-us
osuite logs session-events --range 6h

metrics

Query metrics and discover what is available. metrics query runs PromQL; the other subcommands help you find metric and label names to query — see Querying with PromQL for the query language itself.

Subcommand	Description
search-embedding <query>	Search for metrics and their labels using a phrase.
get-labels <metric>	List the labels available on a metric.
get-label-values <metric> [label]	List values for a label, or for all labels if omitted.
query <promql>	Run a PromQL query.

metrics search-embedding

Find metrics by describing them in words.

osuite metrics search-embedding "CPU usage"
osuite metrics search-embedding "memory consumption" --output json

metrics get-labels

osuite metrics get-labels up
osuite metrics get-labels http_requests_total --output json

metrics get-label-values

Pass a metric to list all its labels and their values, or add a label name to list only that label’s values.

osuite metrics get-label-values http_requests_total
osuite metrics get-label-values http_requests_total status_code
osuite metrics get-label-values up --output json

metrics query

Run a PromQL query. Step size is calculated automatically for range queries from the start and end times.

Option	Description
--range <range>	Relative time range (default 15m).
--start <seconds>	Start time in seconds since the epoch (overrides --range).
--end <seconds>	End time in seconds since the epoch (overrides --range).
--type <type>	Query type: instant or range (default range).

osuite metrics query "up"
osuite metrics query "up" --start 1710460800 --end 1710547200
osuite metrics query "rate(http_requests_total[5m])" --range 1h --type range --output json

The --start and --end times for metrics query are in seconds, unlike the millisecond timestamps used by logs and traces.

traces

Search distributed traces and individual spans. The search commands share the filter syntax and time-range options, and add the contains operator for substring matching.

Subcommand	Description
search	Search traces.
search-span	Search individual spans.
getbyid <traceId>	Fetch one trace by ID, including its full span hierarchy.
getoperations	List service names and their operations.

Common options for search and search-span:

Option	Description
--service <name>	Filter by service name.
--environment <env>	Filter by environment.
--operation <op>	Filter by operation name.
--filter <filters...>	Additional field__operator=value expressions.
--limit <n>	Maximum results to return (default 10).
--range <range>	Relative time range (default 1h).
--start <ms>	Start time in milliseconds since the epoch.
--end <ms>	End time in milliseconds since the epoch.

search also accepts --min-duration <ms> and --max-duration <ms> to bound trace duration.

traces search

osuite traces search --service myservice
osuite traces search --service myservice --filter some.field__is=test
osuite traces search --environment production --filter some.field__is=test --output json
osuite traces search --range 6h --output json

traces search-span

Same options as search, but returns individual spans rather than whole traces.

osuite traces search-span --service myservice
osuite traces search-span --environment production --filter some.field__is=test --output json

traces getbyid

Fetch a single trace by its ID. The response is the complete trace hierarchy, including spans and operations.

osuite traces getbyid <traceId>

traces getoperations

List every service and the operations it emits. Use this to discover valid --operation values before running a search.

Option	Description
--service <service>	Filter operations by a specific service.

osuite traces getoperations
osuite traces getoperations --service myservice

whoami

Print the authenticated user profile. Use it to confirm the CLI is configured and pointed at the right account.

osuite whoami

init-ai

Install the Osuite AI agent skills globally so your AI IDE can invoke them as slash commands. It installs every bundled skill — Instrumentation (/osuite-instrument), Investigation (/osuite-investigate), Visualizer (/osuite-edit-dashboard), and Write PromQL (/osuite-write-promql).

osuite init-ai

See Set up the Osuite AI agents for the full setup, including which AI IDEs are supported.

upgrade

Check npm for the latest CLI release, upgrade the CLI if a newer version exists, and then refresh the installed agent skills. Run it periodically to pick up new skill versions.

osuite upgrade