> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/trailbaseio/trailbase/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Commands

> Complete reference for all TrailBase CLI commands

## Overview

The `trail` CLI is the main entry point for managing TrailBase. It provides commands for running the server, managing users, handling migrations, working with WASM components, and more.

## Global Options

These options are available for all commands:

<ParamField path="--data-dir" type="string" default="./traildepot">
  Directory for runtime files including the database. Will be created by TrailBase if it doesn't exist.

  **Environment variable:** `DATA_DIR`
</ParamField>

<ParamField path="--public-url" type="string">
  Public URL used to access TrailBase. This is necessary for sending valid auth emails and OAuth2 redirects after users authenticate externally.

  **Environment variable:** `PUBLIC_URL`
</ParamField>

<ParamField path="--version" type="boolean">
  Print `trail` version information including git version tag, commit date, and SQLite version.
</ParamField>

## Commands

### run

Starts the HTTP server.

```bash theme={null}
trail run [OPTIONS]
```

<ParamField path="-a, --address" type="string" default="localhost:4000">
  Authority (`<host>:<port>`) the HTTP server binds to.

  **Environment variable:** `ADDRESS`
</ParamField>

<ParamField path="--admin-address" type="string">
  When set, UI and admin APIs will be served separately on this address.

  **Environment variable:** `ADMIN_ADDRESS`
</ParamField>

<ParamField path="--public-dir" type="string">
  Optional path to static assets that will be served at the HTTP root.

  **Environment variable:** `PUBLIC_DIR`
</ParamField>

<ParamField path="--spa" type="boolean" default="false">
  Enable SPA fallback: serve `index.html` for routes (paths without file extensions). File requests (e.g., `/favicon.ico`) will still return 404 if not found. Use with `--public-dir`.

  **Environment variable:** `SPA`
</ParamField>

<ParamField path="--runtime-root-fs" type="string">
  Optional path to sandboxed filesystem root for WASM runtime.

  **Environment variable:** `RUNTIME_ROOT_FS`
</ParamField>

<ParamField path="--geoip-db-path" type="string">
  Optional path to MaxMindDB GeoIP database. Can be used to map logged IPs to a geo location.

  **Environment variable:** `GEOIP_DB_PATH`
</ParamField>

<ParamField path="--dev" type="boolean">
  Use permissive CORS and cookies to allow for cross-origin requests when developing the UI using externally hosted UI (e.g., using a dev server).
</ParamField>

<ParamField path="--demo" type="boolean">
  In demo mode, PII will be redacted from the logs.
</ParamField>

<ParamField path="--stderr-logging" type="boolean" default="false">
  Enable logging to stderr.
</ParamField>

<ParamField path="--cors-allowed-origins" type="string[]" default="*">
  Limit the set of allowed origins the HTTP server will answer to.
</ParamField>

<ParamField path="--runtime-threads" type="number">
  Number of JavaScript isolates/workers to start. Defaults to the number of CPUs.

  **Environment variable:** `RUNTIME_THREADS`
</ParamField>

<CodeGroup>
  ```bash Basic theme={null}
  trail run
  ```

  ```bash Custom Port theme={null}
  trail run --address localhost:8080
  ```

  ```bash Production theme={null}
  trail run \
    --address 0.0.0.0:4000 \
    --public-url https://example.com \
    --data-dir /var/lib/trailbase
  ```

  ```bash Development theme={null}
  trail run --dev --address localhost:3000
  ```
</CodeGroup>

### schema

Export JSON Schema definitions for a table/API.

```bash theme={null}
trail schema <API_NAME> [OPTIONS]
```

<ParamField path="api" type="string" required>
  Name of the table to infer the JSON Schema from.
</ParamField>

<ParamField path="--mode" type="enum">
  Use-case for the type that determines which columns/fields will be required.

  **Values:**

  * `insert` - Insert mode (default)
  * `select` - Read/Select mode
  * `update` - Update mode

  **Environment variable:** `MODE`
</ParamField>

<CodeGroup>
  ```bash Insert Schema theme={null}
  trail schema posts --mode insert
  ```

  ```bash Select Schema theme={null}
  trail schema users --mode select
  ```
</CodeGroup>

### openapi

Export or serve OpenAPI definitions.

#### openapi print

Prints OpenAPI specification to stdout.

```bash theme={null}
trail openapi print
```

<Info>This outputs the complete OpenAPI 3.0 specification in JSON format.</Info>

#### openapi run

<Note>Requires the `swagger` feature to be enabled at compile time.</Note>

Runs a local Swagger UI server.

```bash theme={null}
trail openapi run [OPTIONS]
```

<ParamField path="-a, --address" type="string" default="localhost:4004">
  Authority (`<host>:<port>`) the HTTP server binds to.

  **Environment variable:** `ADDRESS`
</ParamField>

```bash Example theme={null}
trail openapi run --address localhost:8080
```

### migration

Creates a new empty migration file.

```bash theme={null}
trail migration [SUFFIX] [--db DATABASE]
```

<ParamField path="suffix" type="string">
  Optional suffix used for the generated migration file: `U<timestamp>__<suffix>.sql`

  If not provided, defaults to "update".
</ParamField>

<ParamField path="--db" type="string">
  Optional database name. If not provided, defaults to "main".
</ParamField>

<Info>
  Migration files are created with format `U<timestamp>__<suffix>.sql` where the timestamp ensures uniqueness and ordering.
</Info>

<CodeGroup>
  ```bash Default theme={null}
  trail migration
  # Creates: migrations/main/U1234567890__update.sql
  ```

  ```bash Custom Suffix theme={null}
  trail migration add_users_table
  # Creates: migrations/main/U1234567890__add_users_table.sql
  ```

  ```bash Custom Database theme={null}
  trail migration init --db analytics
  # Creates: migrations/analytics/U1234567890__init.sql
  ```
</CodeGroup>

### admin

Manage admin users (list, demote, promote).

#### admin list

Lists all admin users.

```bash theme={null}
trail admin list
```

**Example output:**

```
                                   id	email	created	updated
550e8400-e29b-41d4-a716-446655440000	admin@example.com	2024-01-15T10:30:00Z	2024-03-07T14:22:00Z
```

#### admin promote

Promotes a user to admin.

```bash theme={null}
trail admin promote <USER>
```

<ParamField path="user" type="string" required>
  User identifier, either email address or UUID.
</ParamField>

```bash Example theme={null}
trail admin promote user@example.com
trail admin promote 550e8400-e29b-41d4-a716-446655440000
```

#### admin demote

Demotes an admin user to normal user.

```bash theme={null}
trail admin demote <USER>
```

<ParamField path="user" type="string" required>
  User identifier, either email address or UUID.
</ParamField>

```bash Example theme={null}
trail admin demote admin@example.com
```

### user

Manage users. Unlike the admin UI, this will also let you change admin users.

#### user add

Adds a new and verified user.

```bash theme={null}
trail user add <EMAIL> <PASSWORD>
```

<ParamField path="email" type="string" required>
  Email address of the new user.
</ParamField>

<ParamField path="password" type="string" required>
  Password for the new user. Not checked against password policies.
</ParamField>

```bash Example theme={null}
trail user add user@example.com SecureP@ssw0rd
```

#### user delete

Delete a user.

```bash theme={null}
trail user delete <USER>
```

<ParamField path="user" type="string" required>
  User identifier, either email address or UUID.
</ParamField>

<Warning>This operation is irreversible. All user data will be permanently deleted.</Warning>

```bash Example theme={null}
trail user delete user@example.com
```

#### user change-password

Change a user's password.

```bash theme={null}
trail user change-password <USER> <PASSWORD>
```

<ParamField path="user" type="string" required>
  User identifier, either email address or UUID.
</ParamField>

<ParamField path="password" type="string" required>
  New password to set for the user.
</ParamField>

```bash Example theme={null}
trail user change-password user@example.com NewP@ssw0rd123
```

#### user change-email

Change a user's email address.

```bash theme={null}
trail user change-email <USER> <NEW_EMAIL>
```

<ParamField path="user" type="string" required>
  User identifier, either email address or UUID.
</ParamField>

<ParamField path="new_email" type="string" required>
  New email address to set for the user.
</ParamField>

```bash Example theme={null}
trail user change-email old@example.com new@example.com
```

#### user verify

Change a user's verification state.

```bash theme={null}
trail user verify <USER> [VERIFIED]
```

<ParamField path="user" type="string" required>
  User identifier, either email address or UUID.
</ParamField>

<ParamField path="verified" type="boolean" default="true">
  User's verification state to set.
</ParamField>

<CodeGroup>
  ```bash Verify User theme={null}
  trail user verify user@example.com true
  ```

  ```bash Unverify User theme={null}
  trail user verify user@example.com false
  ```
</CodeGroup>

#### user invalidate-session

Invalidate user sessions, requiring them to re-authenticate when their auth token expires.

```bash theme={null}
trail user invalidate-session <USER>
```

<ParamField path="user" type="string" required>
  User identifier, either email address or UUID.
</ParamField>

```bash Example theme={null}
trail user invalidate-session user@example.com
```

#### user mint-token

Mint an auth token for the given user.

```bash theme={null}
trail user mint-token <USER>
```

<ParamField path="user" type="string" required>
  User identifier, either email address or UUID.
</ParamField>

**Example output:**

```
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

<Info>The output is in Bearer token format and can be used directly in Authorization headers.</Info>

#### user import

Import users from external sources.

```bash theme={null}
trail user import [OPTIONS]
```

<ParamField path="--auth0-json" type="string">
  Path to Auth0 exported users as ND JSON file.
</ParamField>

<ParamField path="-n, --dry-run" type="boolean" default="false">
  In dry-run mode, users will only be validated and not imported.
</ParamField>

<CodeGroup>
  ```bash Dry Run theme={null}
  trail user import --auth0-json users.ndjson --dry-run
  ```

  ```bash Import theme={null}
  trail user import --auth0-json users.ndjson
  ```
</CodeGroup>

### email

Programmatically send emails using the configured email provider.

```bash theme={null}
trail email --to EMAIL --subject SUBJECT --body BODY
```

<ParamField path="--to" type="string" required>
  Receiver address (e.g., `foo@bar.baz`).

  **Environment variable:** `TO`
</ParamField>

<ParamField path="--subject" type="string" required>
  Subject line of the email to be sent.

  **Environment variable:** `SUBJECT`
</ParamField>

<ParamField path="--body" type="string" required>
  Email body, i.e., the actual message.

  **Environment variable:** `BODY`
</ParamField>

<Note>
  Requires email configuration in `config.textproto` or will fall back to the system's `sendmail`.
</Note>

```bash Example theme={null}
trail email \
  --to user@example.com \
  --subject "Welcome to TrailBase" \
  --body "Thank you for joining!"
```

### components

Manage WASM components.

#### components add

Add a new WASM component.

```bash theme={null}
trail components add <REFERENCE>
```

<ParamField path="reference" type="string" required>
  Component reference, which can be:

  * **Name**: First-party component name (e.g., `trailbase/auth_ui`)
  * **URL**: HTTPS URL to a `.wasm` or `.zip` file
  * **Path**: Local filesystem path to a `.wasm` or `.zip` file
</ParamField>

<CodeGroup>
  ```bash First-party Component theme={null}
  trail components add trailbase/auth_ui
  ```

  ```bash From URL theme={null}
  trail components add https://example.com/component.wasm
  ```

  ```bash From Local File theme={null}
  trail components add ./my_component.wasm
  trail components add ./components.zip
  ```
</CodeGroup>

<Info>
  Components are installed to `<data-dir>/wasm/` directory.
</Info>

#### components remove

Remove/delete a WASM component.

```bash theme={null}
trail components remove <REFERENCE>
```

<ParamField path="reference" type="string" required>
  Component reference: name or local path. URLs are not supported for removal.
</ParamField>

<Warning>This permanently deletes the component files from disk.</Warning>

<CodeGroup>
  ```bash Remove by Name theme={null}
  trail components remove trailbase/auth_ui
  ```

  ```bash Remove by Path theme={null}
  trail components remove ./my_component.wasm
  ```
</CodeGroup>

#### components list

List available first-party components.

```bash theme={null}
trail components list
```

**Example output:**

```
Components:

trailbase/auth_ui
```

#### components installed

List installed components with their interfaces.

```bash theme={null}
trail components installed
```

**Example output:**

```json theme={null}
./wasm/auth_ui_component.wasm - interfaces: [
  {
    "name": "auth-ui",
    "namespace": "trailbase",
    "version": "0.1.0",
    "worlds": ["auth-ui"],
    "interfaces": ["login", "register"]
  }
]
```

#### components update

Update all installed first-party components.

```bash theme={null}
trail components update
```

<Info>
  This command checks all installed components and updates those that are first-party components from the official registry.
</Info>

```bash Example Output theme={null}
Updated : ["./wasm/auth_ui_component.wasm"]
```

## Exit Codes

* **0**: Success
* **Non-zero**: Error occurred (error message will be logged)

## Environment Variables

Most CLI options can be set via environment variables. The naming convention is:

* Use `SCREAMING_SNAKE_CASE`
* Drop the `--` prefix
* Replace `-` with `_`

For example:

* `--data-dir` → `DATA_DIR`
* `--public-url` → `PUBLIC_URL`
* `--admin-address` → `ADMIN_ADDRESS`

## Common Workflows

<Accordion title="Start TrailBase for the first time">
  ```bash theme={null}
  # Initialize with default settings
  trail run

  # Server starts on http://localhost:4000
  # Data directory created at ./traildepot/
  ```
</Accordion>

<Accordion title="Create your first admin user">
  ```bash theme={null}
  # Add a user
  trail user add admin@example.com SecurePassword123

  # Promote to admin
  trail admin promote admin@example.com

  # Verify the user
  trail user verify admin@example.com true
  ```
</Accordion>

<Accordion title="Create and apply a database migration">
  ```bash theme={null}
  # Create migration file
  trail migration add_posts_table

  # Edit the generated file in migrations/main/
  # Add your SQL statements

  # Migrations are automatically applied on next startup
  trail run
  ```
</Accordion>

<Accordion title="Install a WASM component">
  ```bash theme={null}
  # List available components
  trail components list

  # Install a component
  trail components add trailbase/auth_ui

  # Verify installation
  trail components installed
  ```
</Accordion>