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 is the complete surface.

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 --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 host, port or data directory, pass the same values here.

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 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 four take --data-dir <path> (default ~/.maple/data).

maple update

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

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

Services

maple services

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

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.

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, --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

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, --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 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 query "<sql>"

Run raw ClickHouse SQL against the local store, for anything the typed commands don’t cover.

• <sql>: the query to run

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

Local only. Raw SQL against the hosted warehouse would let one client read other organizations’ 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 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 → API 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 command except maple query works in remote mode. The server commands (start, stop, reset, checkpoint, restore, 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: a stored credential implies remote; otherwise a quick GET /health probe of the local server implies local. 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.

None means no credential is checked. 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.

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, logs 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.