---
title: "CLI reference"
description: "Manage accounts, databases, keys, storage, recovery, and analytics from the CLI."
section: "Reference"
source_url: "https://sqlstyle.com/docs/cli-reference"
---
Create a controller with an explicit allocation, for example
`sqlstyle database app/main create --write-allowance 1000`. Forking also requires
`--write-allowance`. The account must have enough unallocated controller writes.

Use the web dashboard for signup and billing. Use the CLI to manage databases,
storage, keys, recovery, and analytics.

## Command groups

| Command | Purpose |
| --- | --- |
| `sqlstyle auth` | Sign in, inspect, or remove the local account key |
| `sqlstyle credential` | Inspect and test the selected local credential store |
| `sqlstyle toolbox` | Enable and use the optional encrypted database organizer |
| `sqlstyle database` | Create, list, delete, and restore logical databases |
| `sqlstyle storage profiles` | Create and list non-secret object-storage profiles |
| `sqlstyle keys` | Create, list, and delete database-scoped API keys |
| `sqlstyle database NAME recovery` | Inspect, verify, and safely delete backup objects |
| `sqlstyle analytics` | Download or view centralized analytics |
| `sqlstyle convert` | Convert an offline database between Bedrock and SQLite |
| `sqlstyle version` | Print the CLI version and bundled database core |

Append `--help` to a group or subcommand for its current flags.

## Encrypted Toolbox organizer

Toolbox creates no internal database or configuration until explicitly enabled:

```sh
sqlstyle toolbox setup --config devstack.json5
sqlstyle toolbox import bootstrap.export --secret-file secret
sqlstyle toolbox status
sqlstyle toolbox sync
sqlstyle toolbox dump
sqlstyle toolbox dump --include databases,storage-usage,files --database app/main --refresh
sqlstyle toolbox dump --include storage-costs --database app/main --config database.json5
```

When enabled, database, key, recovery, and remote analytics operations require a
successful Devstack synchronization and are recorded in the encrypted catalog.
Use `sqlstyle toolbox database credentials NAME` to manage saved controller and
object-storage access.

`toolbox dump` emits one JSON document with `databases` and `errors` arrays.
It includes database details and cached storage usage by default. Select data
with `--include databases,storage-usage,files,storage-costs`; explicit selections
replace the defaults. Repeat `--database NAME` to select several saved databases.

`--refresh` scans the selected databases' storage and saves complete inventories.
Without it, usage and file records come from the saved scan; Toolbox still
synchronizes its catalog. File paths are relative to the reported storage
prefix, and file records include byte size, ETag, and modification time. Storage
credentials and API-key values are omitted. Missing cached measurements have
`scan.status` set to `not_cached`; failed reads return structured errors and a
nonzero exit status.

`storage-costs` reads fresh analytics using a saved controller key
and `--config FILE` (or `SQLSTYLE_CONFIG`). The configuration supplies each
database's inline analytics, storage access, and encryption keys. It reports
current UTC calendar-month request/read and capacity costs, projected month-end
totals, and coverage under `storage.costs`.
Amounts use integer nano-USD; unavailable estimates are null with a reason.
These are provider list-price estimates, excluding discounts, credits and taxes.
`--refresh` applies to usage and file inventories; costs always use a fresh
analytics snapshot.

## Offline database conversion

Each toolbox bundles `sqlstyle` and a sibling `sqlite3` linked to the same
database core. Convert a database in place, or write a new database without
changing the source:

```sh
sqlstyle convert bedrock app.db
sqlstyle convert sqlite app.db --output app-sqlite.db
```

Bedrock uses WAL2, and SQLite output uses WAL without a SQLStyle database
identity marker. Conversion requires the database to be offline and refuses
existing output or companion paths.

## Authentication

```sh
sqlstyle auth login
sqlstyle auth status
sqlstyle auth logout
```

Browser login returns an account-scoped credential to the waiting CLI. The credential is stored locally; it is not exposed to frontend JavaScript.

## Databases

```sh
sqlstyle database app/main create --write-allowance 1000
sqlstyle database list
sqlstyle database ls
sqlstyle database app/main delete
```

Creation also accepts account, project, and storage-profile selectors.
`list` and `ls` select the list operation when used alone or with list flags.
When followed by an action, either word is a database name: `sqlstyle database
ls create` creates a database named `ls`.

Restore the latest accepted state to the current directory:

```sh
sqlstyle database app/main restore
```

For `app/main`, the default output is `app_main.sqlite`. Use `--output PATH` to
select another destination. SQLStyle refuses to replace an existing file.
Recovery inspection and maintenance are scoped to the same database name:

```sh
sqlstyle database app/main recovery status
sqlstyle database app/main recovery inventory
sqlstyle database app/main recovery verify --mode plan
sqlstyle database app/main recovery delete --object <object-ref>
```

## Storage profiles

```sh
sqlstyle storage profiles create \
  --name production \
  --provider aws_s3 \
  --bucket app-dbh \
  --region us-east-1 \
  --access-key-id "$AWS_ACCESS_KEY_ID"

sqlstyle storage profiles list
```

Profiles contain the complete non-secret provider configuration: the SQLStyle
account and project association, provider, bucket, region, endpoint, access-key
ID, retention, and checksum mode. Supply only the secret access key locally to
runtime, restore, or analytics commands. For providers such as Cloudflare R2,
the provider account ID is encoded in the stored endpoint; `--account-id`
selects a SQLStyle account.

## Database-scoped keys

```sh
sqlstyle keys create \
  --database app/main \
  --label application-runtime

sqlstyle keys list --database app/main
sqlstyle keys delete --database app/main --key-id <id>
```

When scopes are omitted, key creation uses the default controller-connect, database-read, and config-read scopes.

## Structured output

Resource commands generally support `--out table|json`; some accept `--json` as a shortcut. Key creation defaults to secret-only output and can emit environment format where supported.

For automation, keep progress on standard error and final JSON on standard output.