CLI Reference

Every maple command, argument, and flag — plus the server endpoints, environment variables, and troubleshooting for local mode.

The maple binary is one CLI with two backends: a local server (maple start) and a remote workspace (maple login). Every query command runs against whichever is resolved for that invocation. Output is JSON by default — clean enough to pipe into jq or an agent.

This page is the complete surface. For a guided walkthrough, start with Maple Local.

Global flags

These are accepted by every command (position-independent — maple --local traces and maple traces --local both work):

Flag	Description
`--local`	Force local mode (requires a running `maple start`)
`--remote`	Force remote mode (requires `maple login`)
`--debug`	Print the compiled SQL and per-query timing to stderr (stdout stays clean JSON)
`--format <json\|table>`	Output format; default `json`. `table` renders a flat row set as an aligned table

Most query commands also share a set of filter flags. Defaults and availability vary per command (listed below), but the shapes are consistent:

Flag	Alias	Default	Description
`--since <range>`		`6h`	Relative time range — `30m`, `1h`, `6h`, `24h`, `7d`
`--start <time>`			Absolute start, `YYYY-MM-DD HH:mm:ss` UTC (use with `--end`)
`--end <time>`			Absolute end, `YYYY-MM-DD HH:mm:ss` UTC
`--service <name>`	`-s`		Filter by service name
`--env <name>`	`-e`		Filter by deployment environment (e.g. `production`)
`--limit <n>`	`-n`	`20`	Maximum number of results
`--offset <n>`		`0`	Pagination offset

Server commands

Local mode only. maple start is the long-lived process that owns the embedded chDB connection; the query commands talk to it over HTTP.

`maple start`

Start the local ingest + query server (embedded ClickHouse via chDB).

Flag	Default	Description
`--port <int>`	`4318`	Port for OTLP/HTTP ingest, the query API, and the bundled UI
`--data-dir <path>`	`~/.maple/data`	Embedded ClickHouse data directory
`--offline`	`false`	Serve the UI bundled in this binary (from `127.0.0.1`) instead of `local.maple.dev`
`--background`, `-d`	`false`	Run detached (logs to `~/.maple/maple.log`); stop with `maple stop`
`--reset`	`false`	Wipe the existing store before starting — use after an incompatible upgrade

maple start                    # foreground, UI from local.maple.dev
maple start --offline          # foreground, bundled UI, no internet needed
maple start -d --port 4400     # detached on a custom port

`maple stop`

Stop a running maple start server (reads the PID file beside the data dir).

Flag	Default	Description
`--data-dir <path>`	`~/.maple/data`	Data directory of the server to stop

`maple reset`

Delete the local chDB store so the next maple start bootstraps fresh. Refuses to run while a server still owns the store.

Flag	Default	Description
`--data-dir <path>`	`~/.maple/data`	Store to delete
`--yes`, `-y`	`false`	Skip the confirmation prompt

Services

`maple services`

List active services with throughput, error rate, and P95 latency. Flags: --since / --start / --end, --env.

`maple diagnose <service-name>`

Deep-dive a service: health, top errors, recent traces and logs.

<service-name> — service to diagnose
Flags: --since / --start / --end, --env

`maple service-map`

Service dependency edges (call counts, errors, latency). Flags: --since / --start / --end, --service, --env.

`maple top-ops <service-name>`

Top operations (span names) for a service, ranked by a metric.

<service-name> — service to inspect
--metric <count|avg_duration|p50_duration|p95_duration|p99_duration|error_rate|apdex> — ranking metric (default count)
Flags: --since / --start / --end, --limit

Traces

`maple traces`

Search traces/spans.

Flag	Description
`--span-name <substr>`	Filter by span name (substring, case-insensitive)
`--errors`	Only include traces with errors
`--min-duration-ms <int>`	Minimum duration in milliseconds
`--max-duration-ms <int>`	Maximum duration in milliseconds
`--http-method <method>`	Filter by HTTP method (`GET`, `POST`, …)

Plus --since / --start / --end, --service, --limit, --offset.

maple traces --service api --min-duration-ms 500 --errors --since 1h

`maple trace <trace-id>`

Inspect a trace: full span tree + correlated logs.

<trace-id> — trace ID to inspect

`maple slow-traces`

Find the slowest traces with duration stats. Flags: --since / --start / --end, --service, --env, --limit.

Errors

`maple errors`

List error groups by fingerprint (count, affected services, last seen). Flags: --since / --start / --end, --service, --env, --limit.

`maple error <fingerprint-hash>`

Show detail for one error group: sample traces + timeseries.

<fingerprint-hash> — error fingerprint hash (from the errors command)
Flags: --since / --start / --end, --service, --limit

Logs

`maple logs`

Search logs with filtering.

Flag	Alias	Description
`--severity <level>`		Filter by severity (`TRACE`/`DEBUG`/`INFO`/`WARN`/`ERROR`/`FATAL`)
`--search <text>`	`-q`	Search text (substring match)
`--trace-id <id>`		Filter by trace ID

Plus --since / --start / --end, --service, --limit, --offset.

`maple log-patterns`

Cluster logs into templates to surface the noisiest patterns. Flags: --since / --start / --end, --service, --severity, --search/-q, --limit.

Attributes

maple attributes has two subcommands for discovering attribute keys and values.

`maple attributes keys`

Discover available attribute keys.

Flag	Default	Description
`--source <traces\|metrics\|services>`	`traces`	Attribute source
`--scope <span\|resource>`	`span`	Attribute scope (traces only)

Plus --service, --since / --start / --end, --limit.

`maple attributes values <key>`

List values for an attribute key.

<key> — attribute key to list values for
Flags: same as attributes keys

Metrics and raw SQL

`maple metrics`

List available metrics. Flags: --since / --start / --end, --service, --search/-q, --limit.

`maple query "<sql>"`

Run raw ClickHouse SQL against the local chDB store — an escape hatch for anything the typed commands don’t cover.

<sql> — raw ClickHouse SQL

maple query "SELECT ServiceName, count() FROM traces GROUP BY ServiceName ORDER BY 2 DESC"

Local only. Raw SQL against the multi-tenant cloud warehouse would let a client read other orgs’ data, so maple query returns a clear error in remote mode. Every other command works in both modes.

Analytics

`maple timeseries`

Time-bucketed trace metrics (count, latency quantiles, error rate, apdex emitted per bucket).

Flag	Default	Description
`--group-by <none\|service\|span_name\|status_code\|http_method>`	`none`	Group series by dimension
`--span-name <substr>`		Filter by span name
`--errors`	`false`	Only include errored spans
`--bucket <seconds>`	`60`	Bucket size in seconds

Plus --since / --start / --end, --service, --env.

`maple breakdown`

Top-N trace breakdown by dimension (service, span, status code, http method).

Flag	Default	Description
`--group-by <service\|span_name\|status_code\|http_method>`	`span_name`	Group results by dimension
`--span-name <substr>`		Filter by span name
`--errors`	`false`	Only include errored spans

Plus --since / --start / --end, --service, --env, --limit.

`maple compare`

Compare service health between two time windows (regression detection). Provide either --around or all four explicit window bounds.

Flag	Description
`--around <ts>`	Compare the 30m before vs. after this UTC time (`YYYY-MM-DD HH:mm:ss`)
`--current-start <ts>` / `--current-end <ts>`	The “current” window
`--previous-start <ts>` / `--previous-end <ts>`	The baseline window
`--env <name>`	Filter by deployment environment

Auth and configuration

Remote credentials live in ~/.maple/config.json (mode 0600).

`maple login`

Save remote workspace credentials.

Flag	Description
`--api-url <url>`	Maple API base URL (e.g. `https://api.maple.dev`)
`--token <token>`	API token. If omitted, it’s read from stdin so it stays out of shell history

`maple logout`

Remove the stored remote token from ~/.maple/config.json.

`maple whoami`

Show the resolved mode (local/remote) and target.

`maple use <local|remote|auto>`

Pin the default backend so commands stop auto-detecting, or restore auto-detect.

<mode> — local, remote, or auto (clear the pin)

Mode resolution, per command, in priority order:

--local / --remote flags.
defaultMode pinned via maple use.
Auto-detect — a configured token implies remote; otherwise a quick GET /health probe of the local server implies local. If neither is available, the CLI prints an actionable error.

Server endpoints

maple start binds 127.0.0.1 only (never externally reachable). When --offline is set, the bundled SPA is also served over GET.

Method	Path	Purpose
`GET`	`/health`	Liveness probe (returns `OK`); used by mode auto-detect
`POST`	`/v1/traces`	OTLP traces ingest → `{ "accepted": <rowCount> }`
`POST`	`/v1/logs`	OTLP logs ingest
`POST`	`/v1/metrics`	OTLP metrics ingest
`POST`	`/local/query`	Run SQL: `{ "sql": "..." }` → bare JSON array of rows
`OPTIONS`	`*`	CORS preflight (answers Private Network Access for the `local.maple.dev` UI)

OTLP bodies may be protobuf (default) or JSON, optionally gzip-encoded. The /local/query handler owns the output format — it strips any trailing FORMAT <ident> and re-appends FORMAT JSONEachRow, then wraps the rows into a JSON array, so clients POST their compiled SQL verbatim.

Environment variables

Runtime (CLI + server):

Variable	Default	Purpose
`MAPLE_LOCAL_URL`	`http://127.0.0.1:4318`	Base URL the CLI targets in local mode
`MAPLE_LOCAL_UI_URL`	`https://local.maple.dev`	Deployed dashboard origin `maple start` links to
`MAPLE_LIBCHDB`	(auto)	Explicit path to `libchdb`. Otherwise resolved beside the binary, then `~/.maple/bin/libchdb.{so,dylib}`
`MAPLE_API_URL`	`https://api.maple.dev`	Remote API base URL
`MAPLE_API_TOKEN`		Remote bearer token (overrides the stored value)
`MAPLE_ORG_ID`		Remote org override
`MAPLE_DEBUG`		Set to `1` to enable `--debug`
`MAPLE_FORMAT`	`json`	`json` or `table` — same as `--format`

Installer (scripts/install.sh, env-only):

Variable	Default	Purpose
`MAPLE_VERSION`	`latest`	Release tag to install
`MAPLE_INSTALL_DIR`	`~/.maple/bin`	Where the 2-file bundle is installed
`MAPLE_BIN_DIR`	(auto)	Where `maple` is symlinked onto `PATH`
`MAPLE_SKIP_CHECKSUM`	`0`	Set to `1` to skip SHA-256 verification (air-gapped mirrors only)

The on-disk config at ~/.maple/config.json stores apiUrl, token, orgId, and defaultMode. Env vars take precedence over stored values.

Troubleshooting

libchdb not found. The binary dlopens libchdb relative to its own path, then falls back to ~/.maple/bin. Keep libchdb.so/.dylib beside maple, or set MAPLE_LIBCHDB to its full path. (Running from source has no sibling library — set MAPLE_LIBCHDB or drop one in ~/.maple/bin.)

maple is already running (PID …). A server already owns this data dir. Stop it with maple stop, or start a second instance on another port and data dir: maple start --port 4400 --data-dir ~/.maple/data-2.

Incompatible store after an upgrade. If a new binary refuses to open an older store (the local store … is incompatible), wipe it with maple reset, or start fresh in one step with maple start --reset.

Browser asks to “access devices on your local network” (or CORS errors). The default dashboard at local.maple.dev is a public origin reaching your loopback server, which trips Chrome’s Private Network Access gate. Run maple start --offline to serve the dashboard same-origin from 127.0.0.1 — no prompt, no internet needed.

No data appearing. Confirm your exporter points at http://127.0.0.1:<port> and the server is up (maple whoami, or curl 127.0.0.1:4318/health). Widen the time range (--since 24h — the default is 6h). Local mode stores everything under org_id = "local"; a successful ingest responds { "accepted": <n> }.

No Maple backend found. No mode could be resolved: start local mode (maple start) or connect a workspace (maple login), or force one with --local / --remote.