CLI reference

The rtree CLI accesses RawTree through the RawTree Cloud or RawTree BYOC service API.

Install

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

Common options

The root command and subcommands accept these options:

The root command also accepts -v and --version. The --database option is available only on commands that use a database.

Environment variables

An explicit option takes priority over its environment variable. The environment variable takes priority over saved configuration.

Commands

Authentication

rtree login starts device approval. Use --no-browser to print the approval link without opening it. --timeout-seconds sets the wait time. The default is 300 seconds.

Use --api-key to save an API key without device approval. Use --org, --cluster, and --database to save resource defaults.

When standard input is not a terminal, login prints JSON automatically. Use --json to select JSON output explicitly. Other commands need --json for JSON output.

Browser login writes an event to standard error before it polls for approval:

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

Open verification_uri_complete to approve the request. If a resource selection has multiple choices, login prints a JSON response and 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"]}

Repeat login with the requested option. Keep the values selected in earlier steps. A successful login writes its result to standard output.

Databases

database use sets the default database. database delete deletes that database and its data.

API keys

Key permissions are admin, read_write, write_only, and read_only. --database sets the new key's default database. Omit --expires-at for a key that does not expire.

Organizations

Clusters

Tables

The sorting key is a comma-separated list of SQL expressions. Quote it in the shell when it contains shell metacharacters.

Workflows

Use either a relative time such as 1h or RFC 3339 timestamps for workflow logs and metrics. Use --enable or --disable to change a workflow's state. Use --clear-sinks to remove all sinks.

Logs

rtree logs accepts these filters:

• --search, --methods, --status-codes, --levels, --sources
• --user-agent, --host, --paths
• --min-duration-ms, --max-duration-ms
• --since, --until, --start-time, --end-time
• --limit, --offset

Query and format

Use - as the SQL value to read from standard input. query --limit appends a LIMIT clause.

rtree query "SELECT 1"

rtree format "SELECT 1"

Service accounts

Organization admins can create and list service accounts after rtree login:

rtree service-account create build-jobs --org team-alpha --description "CI workloads"
rtree service-account create deployment --org team-alpha --role admin
rtree service-account list --org team-alpha --json

The role defaults to member. Names are immutable and unique within the organization: use 1–128 lowercase letters or digits separated by single hyphens. Descriptions accept up to 2000 UTF-8 bytes without null characters.

These commands use the usual organization selection and require no cluster or database. API keys cannot create or list service accounts. Creation returns an identity without credentials; API key permissions are configured separately. With --json, creation returns the account object and listing returns {"service_accounts":[...]}.

Insert

rtree insert requires --table <TABLE> and one of these data sources:

Use --database <DATABASE> to select the database. Use --transform <TRANSFORM> to apply a predefined transform. See Transforms for supported names and input shapes.

Utilities

Related

• API reference
• Authentication