signoz auth login --url https://signoz.example.com --token sk-xxx

Non-interactive


Credentials are stored securely in macOS Keychain (`security`) or Linux libsecret (`secret-tool`).

### Option 2: Environment variables

```bash
export SIGNOZ_URL=https://signoz.example.com
export SIGNOZ_TOKEN=sk-xxx

Option 3: Per-command flags

Every command accepts --url and --token to override credentials for that invocation.

signoz query --url https://signoz.example.com --token sk-xxx --promql 'up'

Logout

signoz auth logout

Commands

query — Unified query API

Query traces, logs, and metrics. Supports three input modes (mutually exclusive):

Flag	Description
`--promql <expr>`	PromQL expression
`--sql <query>`	ClickHouse SQL query (must include timestamp WHERE clause — see below)
`-f, --file <path>`	Load full query_range JSON body from file

Time range, output, and auth options:

Flag	Default	Description
`--since <time>`	`1h`	Start time — duration ago (`1h`, `30m`, `7d`) or ISO date
`--until <time>`	`now`	End time — `now`, duration ago, or ISO date
`--step <seconds>`	`60`	Step interval in seconds (PromQL only, must be a positive number)
`--format <format>`	`json`	Output: `json`, `table`, or `text`
`--url <url>`		SigNoz API base URL override
`--token <token>`		SigNoz API token override

Duration = "ago": --since 1h means "1 hour ago". --until 1d means "1 day ago" (not "for 1 day"). So --since 7d --until 1d queries from 7 days ago to 1 day ago.

--since/--until only affect PromQL and file mode. For --sql, you must write your own timestamp WHERE clause in the SQL — the start/end values are set in the request body but SigNoz does not auto-inject time filters into raw ClickHouse SQL.

PromQL examples

# Request rate over the last hour
signoz query --promql 'rate(http_requests_total[5m])' --since 1h

# Table output for quick scan
signoz query --promql 'up' --format table

# From a specific start date to now
signoz query --promql 'process_cpu_seconds_total' --since 2024-01-15T00:00:00Z

ClickHouse SQL examples

# Count logs from the last 24 hours (note: timestamp filter is IN the SQL)
signoz query --sql "
  SELECT toStartOfInterval(fromUnixTimestamp64Nano(timestamp), INTERVAL 1 HOUR) AS ts,
         count(*) AS value
  FROM signoz_logs.distributed_logs_v2
  WHERE timestamp >= $(date -d '24 hours ago' +%s)000000000
    AND timestamp <= $(date +%s)000000000
  GROUP BY ts ORDER BY ts
"

# Load a saved query from file with custom time range
signoz query -f my-query.json --since 7d --until 1d

File format for `-f`

The JSON file should follow the SigNoz v5 query_range body format. The start and end fields are overridden by --since/--until:

{
  "requestType": "time_series",
  "compositeQuery": {
    "queries": [
      {
        "type": "promql",
        "spec": { "name": "A", "query": "rate(http_requests_total[5m])", "step": 60, "disabled": false }
      }
    ]
  }
}

alerts — List alert rules

signoz alerts                  # Human-readable text output
signoz alerts --format json    # Machine-readable JSON
signoz alerts --url https://signoz.example.com --token sk-xxx

services — List services

signoz services                # Human-readable text output
signoz services --format json  # Machine-readable JSON

API Endpoints

The CLI talks to these SigNoz API endpoints:

Command	Method	Endpoint
`query`	POST	`/api/v5/query_range`
`alerts`	GET	`/api/v1/rules`
`services`	GET	`/api/v1/services/list`

Default base URL: http://localhost:3301 (SigNoz local dev).

Auth Header

SigNoz uses a custom auth header SIGNOZ-API-KEY (not Authorization: Bearer). This is handled automatically by the CLI.

Duration Format

Relative durations for --since and --until always mean "X ago from now":

Unit	Example	Meaning
`s`	`30s`	30 seconds ago
`m`	`15m`	15 minutes ago
`h`	`2h`	2 hours ago
`d`	`7d`	7 days ago

ISO 8601 dates are also accepted: 2024-01-15T00:00:00Z.

ClickHouse SQL Reference for SigNoz

This section documents SigNoz-specific ClickHouse SQL conventions that differ from standard SQL. You must follow these conventions when using --sql.

Tables and Timestamp Formats

Each signal type uses different tables and timestamp formats:

Signal	Database.Table	Timestamp Column	Format	Filter Example
Logs	`signoz_logs.distributed_logs_v2`	`timestamp`	UInt64 nanoseconds	`timestamp >= 1711234567000000000`
Traces	`signoz_traces.distributed_signoz_index_v3`	`timestamp`	DateTime64(9), must quote	`timestamp >= '1711234567000000000'`
Metrics	`signoz_metrics.distributed_samples_v4`	`unix_milli`	Int64 milliseconds	`unix_milli >= 1711234567000`

Always use distributed_* tables (not local tables like logs_v2 or signoz_index_v3).

Required: `ts_bucket_start` Filter (Logs & Traces)

Logs and Traces tables have ts_bucket_start (UInt64, epoch seconds) in their primary key. Always include it for query performance — without it, queries may be extremely slow or time out.

WHERE timestamp >= {startNano} AND timestamp <= {endNano}
  AND ts_bucket_start >= {startSeconds - 1800} AND ts_bucket_start <= {endSeconds}

The -1800 (30 min) buffer on ts_bucket_start ensures edge-case rows aren't missed.

Result Column Naming Convention

SigNoz expects specific column names in ClickHouse SQL results:

Column	Requirement
Time	Must be named `ts`, type DateTime/DateTime64
Value	Named `value`, `__result`, `__value`, `result`, or `res` (auto-detected if only one numeric column)
Labels	All String columns become series labels (used for groupBy)

Complete Query Templates

Logs — Count by severity (last 1 hour)

SELECT toStartOfInterval(fromUnixTimestamp64Nano(timestamp), INTERVAL 1 MINUTE) AS ts,
       severity_text,
       count(*) AS value
FROM signoz_logs.distributed_logs_v2
WHERE timestamp >= {startNano} AND timestamp <= {endNano}
  AND ts_bucket_start >= {startSec - 1800} AND ts_bucket_start <= {endSec}
GROUP BY ts, severity_text
ORDER BY ts

Key log columns: severity_text (INFO/ERROR/...), severity_number, body (message), trace_id, span_id, scope_name.

Traces — P99 latency by service (last 1 hour)

SELECT toStartOfInterval(timestamp, INTERVAL 1 MINUTE) AS ts,
       resource_string_service$$name AS service,
       quantile(0.99)(duration_nano) / 1e6 AS value
FROM signoz_traces.distributed_signoz_index_v3
WHERE timestamp >= '{startNano}' AND timestamp <= '{endNano}'
  AND ts_bucket_start >= {startSec - 1800} AND ts_bucket_start <= {endSec}
GROUP BY ts, service
ORDER BY ts

Key trace columns: name (span name), kind_string, duration_nano (Float64, nanoseconds), status_code (0=unset, 1=ok, 2=error), has_error (Bool), resource_string_service$$name (service name — note $$ encodes .).

Metrics — Average metric value (last 1 hour)

SELECT toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), INTERVAL 1 MINUTE) AS ts,
       avg(value) AS value
FROM signoz_metrics.distributed_samples_v4
WHERE metric_name = 'http_requests_total'
  AND unix_milli >= {startMs} AND unix_milli < {endMs}
GROUP BY ts
ORDER BY ts

Attribute Access (Map Columns)

Non-materialized attributes are stored in Map columns, not regular columns:

-- String attributes
attributes_string['http.method']
resources_string['service.name']
scope_string['otel.library.name']

-- Numeric / Boolean attributes
attributes_number['http.status_code']
attributes_bool['error']

-- Check existence
mapContains(attributes_string, 'http.method')

$$ encoding: Materialized columns encode . as $$. For example, service.name → resource_string_service$$name. Use materialized columns when available for better performance.

Additional Tables

Database	Table	Purpose
`signoz_logs`	`distributed_logs_v2_resource`	Log resource attributes (join via `resource_fingerprint`)
`signoz_traces`	`distributed_traces_v3_resource`	Trace resource attributes
`signoz_traces`	`distributed_top_level_operations`	Top-level operation lookup
`signoz_metrics`	`distributed_time_series_v4`	Metric time series metadata
`signoz_metrics`	`distributed_samples_v4_agg_5m`	5-minute pre-aggregated metrics
`signoz_metrics`	`distributed_samples_v4_agg_30m`	30-minute pre-aggregated metrics

Use GLOBAL IN (not IN) when joining with resource tables in distributed queries.

Troubleshooting

Error	Fix
"No API token configured"	Run `signoz auth login` or set `SIGNOZ_TOKEN`
Connection refused	Check that SigNoz is running at the configured URL
401 Unauthorized	Verify your API token is valid
Query timeout	Add `ts_bucket_start` filter to your SQL WHERE clause
Empty results with `--sql`	Ensure your SQL has timestamp WHERE clause — `--since`/`--until` don't filter SQL
invalid --step value	`--step` must be a positive number in seconds (e.g., `60`, not `1m`)

signoz-cli

signoz CLI

Install

Authentication

Option 1: System keychain (recommended)