CLI reference

The maple binary is one CLI with two backends: the local server it starts itself (maple start) and a hosted Maple workspace (maple auth login). Every query command runs against whichever backend is resolved for that invocation. Output is JSON by default, clean enough to pipe into jq or an agent.

New here? Start with the Maple Local walkthrough, or use the CLI with hosted Maple. This page lists every command.

Command index

Global flags

Accepted by every command, in any position (maple --local traces and maple traces --local both work):

Most query commands also share a set of filter flags. Which ones apply is listed per command below; the shapes are always the same:

Server commands

Local mode only. maple start is the long-lived process that owns the embedded ClickHouse connection; every other command talks to it over HTTP.

maple start

Start the local ingest and query server.

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 start --in-memory        # throwaway store, deleted on exit
maple start --host 0.0.0.0 --advertise-host maple.home.arpa --offline

The default recovery policy is fail, so an unclean shutdown never silently deletes telemetry. What each policy does, and how reset and restore protect the store, is on Checkpoints and archives.

maple stop

Stop a running server. Reads the PID file beside the data directory.

maple reset

Delete live data so the next maple start bootstraps fresh. Checkpoints under <data-dir>/backups are kept. Refuses to run while a server owns the store.

maple checkpoint

Create and validate a restorable checkpoint of the local store. Works out of the box against a running maple start.

If the server was started with a custom data directory, pass the same one. Without --port, the command reads the server’s address from the store’s discovery file.

maple restore

Restore the local store from the current checkpoint. Refuses to run while a server owns the store. The existing store is moved beside the data directory as <data-dir>.quarantine-<ids>, never deleted; maple schema gc lists it and --apply removes it.

maple restore --yes
maple restore --checkpoint-id 01234567-89ab-4cde-8fab-0123456789ab --yes

maple delete

Delete one service’s or namespace’s telemetry from the local store, in the raw tables and every derived rollup. Local mode only. Without --yes it only prints what would be deleted.

maple delete --service checkout-pr-42          # preview
maple delete --namespace pr-42 --yes
maple delete --service api --before 7d --yes

maple archive

Local mode only. Export whole UTC days of the six raw telemetry tables from a checkpoint into Parquet files, and manage those exports. How archives work is explained on Checkpoints and archives.

Signals: logs, traces, metrics_sum, metrics_gauge, metrics_histogram, metrics_exponential_histogram.

Common flags: --data-dir (default ~/.maple/data), --archive-dir (default ~/.maple/archive) and --scratch-root (default ~/.maple/scratch). gc, expire and retire-live change nothing unless you pass --apply. reconcile acts by default; pass --dry-run to print the plan without changing anything.

Export settings are fixed: one writer thread, 10,000-row row groups, and files of at most 500,000 rows or 256 MiB. Older releases had archive calibrate; archive create still accepts its --config flag but ignores it.

maple schema

Inspect and migrate the local store’s schema. Needed only when a release note says a store needs migrating; a normal upgrade opens the store as is.

All five take --data-dir <path> (default ~/.maple/data).

maple update

Update a script-installed binary to the latest release: download, verify the checksum and release signature, install in place.

Homebrew installs refuse maple update so the package manager stays in charge; run brew upgrade maple instead.

maple changelog

Print the release notes for the installed version. --since <version> prints every release after that version instead (maple changelog --since 0.0.20). Text by default; --format json for JSON.

Services

maple services

List active services with throughput, error rate and P95 latency. Flags: --since / --start / --end, --env, --service/-s (services whose name contains the text), --limit (default 50).

maple diagnose <service-name>

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

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

maple service-map

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

• edges: service-to-service calls, drawn when an instrumented callee continues the caller’s trace
• databases: calls from client spans with db.system.name (or the legacy db.system), keyed by system and db.namespace
• external: HTTP, messaging and RPC targets that are not a traced service; listed only with --service, since that query is scoped to one caller

Databases and external calls are local-only. In remote mode the command prints edges, and --service keeps that service’s outbound edges only; locally it keeps both directions.

maple top-ops <service-name>

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

• <service-name>: the 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 and spans.

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

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

maple trace <trace-id>

Inspect one trace: the full span tree plus correlated logs.

• <trace-id>: the trace to inspect, 32 hex characters
• Flags: --since / --start / --end. With none set, the command looks back 24 hours, then up to 30 days

maple slow-traces

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

Errors

maple errors

Error groups by fingerprint, with count, affected services and last seen. Flags: --since / --start / --end, --service, --env, --limit.

maple error <fingerprint-hash>

One error group in detail: sample traces and a timeseries.

• <fingerprint-hash>: the fingerprint from maple errors
• Flags: --since / --start / --end, --service, --limit

Logs

maple logs

Search logs.

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

maple log-patterns

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

Attributes

maple attributes keys

Discover the attribute keys present in your data.

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

maple attributes values <key>

List the values seen for one attribute key.

• <key>: the attribute key
• Flags: same as attributes keys

Metrics and raw SQL

maple metrics

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

maple metrics show <metric-name>

One metric’s values over time, per service. Monotonic counters are shown as a per-second rate, every other type as the average per bucket.

• <metric-name>: the exact metric name, from maple metrics
• --bucket <seconds>: bucket size, default about 60 buckets over the window
• Flags: --since / --start / --end, --service, --env (local mode only)

maple metrics show http.server.request.count --since 1h

maple query "<sql>"

Run a read-only ClickHouse SELECT, for anything the typed commands don’t cover. Writes, multiple statements and table functions are rejected.

• <sql>: the query to run
• Flags: --since / --start / --end, the window the macros use

The macros $__orgFilter, $__timeFilter(col), $__startTime, $__endTime and $__interval_s expand in both modes (see SQL). Locally, SQL without macros also runs as written. Remote queries must include $__orgFilter and return at most 100 rows. Quote the SQL in single quotes so the shell leaves $__ alone:

maple query "SELECT ServiceName, count() FROM traces GROUP BY ServiceName ORDER BY 2 DESC"   # local
maple query 'SELECT ServiceName, count() AS spans FROM traces WHERE $__orgFilter AND $__timeFilter(Timestamp) GROUP BY ServiceName' --since 1h

Analytics

maple timeseries

Time-bucketed trace metrics: count, latency quantiles, error rate and apdex per bucket.

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

maple breakdown

Top-N breakdown of traces by a dimension.

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

maple compare

Compare service health between two windows, for regression detection. Give either --around or all four explicit bounds.

Using the CLI with hosted Maple

The query commands also work against a hosted Maple organization. Sign in once:

maple auth login                                   # US organizations
maple auth login --api-url https://api.eu.maple.dev # EU organizations
maple use remote                                   # optional: stop auto-detecting
maple services --since 1h

maple auth login opens your browser, and you approve the CLI for one organization. The CLI then holds an API key with full access that expires after 90 days. It appears under Settings → Keys with the description “Created by maple auth login”. Run maple auth login again when it expires, and maple auth logout to revoke it.

Every query command works in remote mode, maple query included. The server commands (start, stop, reset, checkpoint, restore, delete, archive, schema) always act on the local store. Which region your organization is in is on Regions.

Auth and configuration

maple auth login

Sign in to a hosted Maple workspace. Opens your browser to approve the CLI; the credential is stored in the macOS keychain where available, otherwise in ~/.maple/config.json (mode 0600). maple login is a shorthand for the same command.

maple auth login
echo "$MAPLE_TOKEN" | maple auth login --with-token

maple auth status

Show and validate the active login: API URL, user, workspace and where the credential is stored.

maple auth logout

Revoke the credential with the API and remove it locally. maple logout is the shorthand. A token supplied through MAPLE_API_TOKEN cannot be removed this way; unset the variable instead.

maple whoami

Show the resolved mode (local or remote) and the target it would talk to, plus any pinned default.

maple use <local|remote|auto>

Pin the default backend so commands stop auto-detecting, or auto to clear the pin.

Mode resolution, per command, in priority order:

1. An explicit --local or --remote flag.
2. The default pinned with maple use.
3. Auto-detect: an explicitly set MAPLE_LOCAL_URL means local; otherwise a stored credential means remote; otherwise the CLI probes the local server (GET /local/status, falling back to /health for older binaries). If neither is available the CLI prints what to do next.

Server endpoints

maple start binds 127.0.0.1 by default. --host or MAPLE_LOCAL_BIND_HOST can select another address. Every route below is then reachable from the network, so set the two secrets below whenever you do.

Ingest key and Access token apply only when MAPLE_LOCAL_INGEST_KEY and MAPLE_LOCAL_ACCESS_TOKEN are set (each at least 16 characters; openssl rand -hex 32 makes a good one). Unset, those routes check nothing, and on a non-loopback bind anyone who can reach the port can read all local telemetry through /local/query and write to it through OTLP. maple start warns when that is the case.

• The ingest key goes in Authorization: Bearer <key> or x-maple-ingest-key, the same headers Maple’s hosted ingest accepts, so an exporter configured for Maple only needs its endpoint changed. It never grants a read.
• The access token signs browsers in through /login (a 30-day, HttpOnly session cookie; rotating the token signs everyone out) and is accepted as Authorization: Bearer <token> by scripts. CLI commands send it when MAPLE_LOCAL_ACCESS_TOKEN is set in their environment. Ten failed sign-ins within a minute lock the sign-in form for everyone until the minute passes; Bearer requests and existing sessions are unaffected.
• With an access token set, the dashboard works on whatever hostname reaches it (a platform URL, a reverse proxy), without --advertise-host.

Behind an authenticating proxy

A server exposed through a proxy that checks its own credentials (Cloudflare Access, an auth gateway) also needs those credentials on every CLI request. Set MAPLE_LOCAL_HEADERS to comma-separated name=value pairs, the same format as OTEL_EXPORTER_OTLP_HEADERS (values may be percent-encoded). The CLI sends them only to the MAPLE_LOCAL_URL origin, and never in place of a header it already sets:

MAPLE_LOCAL_URL=https://maple.example.com \
MAPLE_LOCAL_HEADERS='CF-Access-Client-Id=<id>,CF-Access-Client-Secret=<secret>' \
maple services

For Cloudflare Access with your own identity instead of a service token, sign in once with cloudflared:

cloudflared access login https://maple.example.com
MAPLE_LOCAL_URL=https://maple.example.com maple services

When MAPLE_LOCAL_URL is https on another host and MAPLE_LOCAL_HEADERS carries no Access credential, the CLI asks cloudflared access token for the cached token once per command and sends it as cf-access-token. Without cloudflared or a cached token it sends nothing extra. If the proxy still refuses or redirects to a sign-in page, the command says so and names both fixes.

The maintenance token is sent in x-maple-maintenance-token and the event consumer token in x-maple-event-consumer-token. maple start creates them on first run as <data-dir>.maintenance-token and <data-dir>.event-consumer-token (mode 0600). Anyone who can read those files can call the token routes, including /local/retention/retire, which deletes data. The event routes are described in the local event consumers design doc.

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

Environment variables

Runtime (CLI and server):

CLI telemetry. The CLI sends its own traces and metrics (service maple-cli) to Maple by default. See What connects to the internet for what is recorded.

Install script (scripts/install.sh):

~/.maple/config.json stores apiUrl, orgId, defaultMode and, when the keychain is unavailable, the token. Environment variables take precedence over stored values.

Troubleshooting

libchdb not found. The binary loads libchdb from beside its own path, then falls back to ~/.maple/bin. Homebrew keeps maple and libchdb together; the install script keeps them in ~/.maple/bin. If you moved files by hand, keep libchdb.so or .dylib beside maple, or set MAPLE_LIBCHDB to its full path. Running from source has no sibling library, so set MAPLE_LIBCHDB or drop one into ~/.maple/bin.

Homebrew installed, but maple still runs the old binary. A script-installer symlink is earlier on PATH. Confirm with command -v maple, then remove the old symlink or run curl -fsSL https://maple.dev/cli/uninstall | sh before reinstalling with Homebrew.

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

Incompatible store after an upgrade. A new binary that refuses an older store (the local store … is incompatible) needs the live data cleared: maple reset --yes, or maple start --reset in one step. Both keep checkpoints. If the release notes call for a migration instead, use maple schema.

Store was not cleanly closed. The default --on-dirty-store fail stops rather than guess. Restart with --on-dirty-store restore-checkpoint to roll back to the last good checkpoint, or wipe to discard live data. Neither touches checkpoints.

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 gate. Run maple start --offline to serve the dashboard same-origin. For a wildcard LAN bind, also set --advertise-host to the hostname the browser will use; other hosts and origins are rejected.

Authentication proxy blocks the bundled UI. The UI works behind TLS with browser-managed authentication such as a session cookie or HTTP auth. It does not inject a bearer token or copy an entry-page query parameter into its /local/query and OTLP requests.

No data appearing. Confirm the exporter points at the advertised host and port and the server is up (maple whoami, or curl <host>:4318/health). Widen the time range; the default is --since 6h. A successful ingest responds { "accepted": <n> }.

No Maple backend found. Neither backend could be resolved. Start local mode (maple start), sign in to a workspace (maple auth login), or force one with --local / --remote.