CLI reference

The RawTree CLI command is rtree.

Install

curl -fsSL https://rawtree.com/install.sh | bash

Global options

Environment variables

Resolution order:

• Database: --database, then RAWTREE_DATABASE, then saved config.
• Organization: --org, then RAWTREE_ORG, then saved config.
• API key: --api-key, then RAWTREE_API_KEY, then saved credentials from rtree login.

Authentication

rtree login
rtree login --api-key rt_...
rtree login --org team-alpha --cluster production --database analytics
rtree logout
rtree status

Interactive login opens a browser for approval and prompts for resource selections. Use --no-browser to print the approval link without opening it. Approval can be completed in a browser on another device.

Non-interactive login

rtree login uses JSON automatically when stdin is not a terminal. You can also select JSON explicitly with --json. Other commands still require --json for JSON output.

Browser login emits this event to stderr before polling for approval:

{"event":"device_approval_required","verification_uri":"<approval page>","verification_uri_complete":"<approval link>","user_code":"ABCD-EFGH","expires_in":600}

Read stderr as newline-delimited JSON while the command is running. Open the verification_uri_complete link to approve; JSON mode does not launch a browser. --timeout-seconds controls how long the CLI waits (default: 300 seconds, capped by the device code's lifetime).

After approval, an omitted selection is filled automatically if exactly one option exists. Otherwise, stdout contains one of the following responses and the process exits with code 2:

{"needs":"org","orgs":["team-alpha","team-beta"]}
{"needs":"cluster","organization":"team-alpha","clusters":["production","staging"]}
{"needs":"database","organization":"team-alpha","cluster":"production","databases":["analytics","billing"]}

Rerun with the matching --org, --cluster, or --database flag, keeping any previously selected values. An empty choices array means no resources are available at that level. Each retry starts a new device approval; incomplete logins leave existing credentials and defaults unchanged.

Successful login writes the final JSON result to stdout and exits with code 0. Invalid selections, approval failures, and API failures produce a JSON error on stderr and a nonzero exit. API-key login skips device approval entirely.

Databases

rtree database list
rtree database create analytics
rtree database use analytics
rtree database delete analytics

Organizations

rtree organization list
rtree organization create team-alpha
rtree organization use team-alpha
rtree organization rename team-alpha team-beta
rtree organization delete team-beta

Insert

rtree insert --table events --data '{"action":"click"}'
rtree insert --table events --file ./events.jsonl
rtree insert --table events --url https://example.com/events.jsonl
rtree insert --table traces --data '{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"api"}}]},"scopeSpans":[{"spans":[{"name":"GET /health","spanId":"abc"}]}]}' --transform otlp-traces

See Transforms for supported transform names, input shapes, and emitted rows, including the AWS Firehose HTTP endpoint transform.

Query

rtree query "SELECT * FROM events LIMIT 10"
rtree query --sql "SELECT count() FROM events"
cat query.sql | rtree query -
rtree query --limit 10 "SELECT * FROM events"

Tables

rtree table list
rtree table describe events

API keys

rtree key list
rtree key create --name ci --permission read_write
rtree key delete <id_or_token>

Utility

rtree ping
rtree docs
rtree open
rtree completions zsh