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:

string

default:"./traildepot"

Directory for runtime files including the database. Will be created by TrailBase if it doesn’t exist.Environment variable: DATA_DIR

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

boolean

Print trail version information including git version tag, commit date, and SQLite version.

Commands

run

Starts the HTTP server.

trail run [OPTIONS]

string

default:"localhost:4000"

Authority (<host>:<port>) the HTTP server binds to.Environment variable: ADDRESS

string

When set, UI and admin APIs will be served separately on this address.Environment variable: ADMIN_ADDRESS

string

Optional path to static assets that will be served at the HTTP root.Environment variable: PUBLIC_DIR

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

string

Optional path to sandboxed filesystem root for WASM runtime.Environment variable: RUNTIME_ROOT_FS

string

Optional path to MaxMindDB GeoIP database. Can be used to map logged IPs to a geo location.Environment variable: GEOIP_DB_PATH

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).

boolean

In demo mode, PII will be redacted from the logs.

boolean

default:"false"

Enable logging to stderr.

string[]

default:"*"

Limit the set of allowed origins the HTTP server will answer to.

number

Number of JavaScript isolates/workers to start. Defaults to the number of CPUs.Environment variable: RUNTIME_THREADS

trail run

trail run --address localhost:8080

trail run \
  --address 0.0.0.0:4000 \
  --public-url https://example.com \
  --data-dir /var/lib/trailbase

trail run --dev --address localhost:3000

schema

Export JSON Schema definitions for a table/API.

trail schema <API_NAME> [OPTIONS]

string

required

Name of the table to infer the JSON Schema from.

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

trail schema posts --mode insert

trail schema users --mode select

openapi

Export or serve OpenAPI definitions.

openapi print

Prints OpenAPI specification to stdout.

trail openapi print

This outputs the complete OpenAPI 3.0 specification in JSON format.

openapi run

Requires the swagger feature to be enabled at compile time.

Runs a local Swagger UI server.

trail openapi run [OPTIONS]

string

default:"localhost:4004"

Authority (<host>:<port>) the HTTP server binds to.Environment variable: ADDRESS

Example

trail openapi run --address localhost:8080

migration

Creates a new empty migration file.

trail migration [SUFFIX] [--db DATABASE]

string

Optional suffix used for the generated migration file: U<timestamp>__<suffix>.sqlIf not provided, defaults to “update”.

string

Optional database name. If not provided, defaults to “main”.

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

trail migration
# Creates: migrations/main/U1234567890__update.sql

trail migration add_users_table
# Creates: migrations/main/U1234567890__add_users_table.sql

trail migration init --db analytics
# Creates: migrations/analytics/U1234567890__init.sql

admin

Manage admin users (list, demote, promote).

admin list

Lists all admin users.

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.

trail admin promote <USER>

string

required

User identifier, either email address or UUID.

Example

trail admin promote user@example.com
trail admin promote 550e8400-e29b-41d4-a716-446655440000

admin demote

Demotes an admin user to normal user.

trail admin demote <USER>

string

required

User identifier, either email address or UUID.

Example

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.

trail user add <EMAIL> <PASSWORD>

string

required

Email address of the new user.

string

required

Password for the new user. Not checked against password policies.

Example

trail user add user@example.com SecureP@ssw0rd

user delete

Delete a user.

trail user delete <USER>

string

required

User identifier, either email address or UUID.

This operation is irreversible. All user data will be permanently deleted.

Example

trail user delete user@example.com

user change-password

Change a user’s password.

trail user change-password <USER> <PASSWORD>

string

required

User identifier, either email address or UUID.

string

required

New password to set for the user.

Example

trail user change-password user@example.com NewP@ssw0rd123

user change-email

Change a user’s email address.

trail user change-email <USER> <NEW_EMAIL>

string

required

User identifier, either email address or UUID.

string

required

New email address to set for the user.

Example

trail user change-email old@example.com new@example.com

user verify

Change a user’s verification state.

trail user verify <USER> [VERIFIED]

string

required

User identifier, either email address or UUID.

boolean

default:"true"

User’s verification state to set.

trail user verify user@example.com true

trail user verify user@example.com false

user invalidate-session

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

trail user invalidate-session <USER>

string

required

User identifier, either email address or UUID.

Example

trail user invalidate-session user@example.com

user mint-token

Mint an auth token for the given user.

trail user mint-token <USER>

string

required

User identifier, either email address or UUID.

Example output:

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The output is in Bearer token format and can be used directly in Authorization headers.

user import

Import users from external sources.

trail user import [OPTIONS]

string

Path to Auth0 exported users as ND JSON file.

boolean

default:"false"

In dry-run mode, users will only be validated and not imported.

trail user import --auth0-json users.ndjson --dry-run

trail user import --auth0-json users.ndjson

email

Programmatically send emails using the configured email provider.

trail email --to EMAIL --subject SUBJECT --body BODY

string

required

Receiver address (e.g., foo@bar.baz).Environment variable: TO

string

required

Subject line of the email to be sent.Environment variable: SUBJECT

string

required

Email body, i.e., the actual message.Environment variable: BODY

Requires email configuration in config.textproto or will fall back to the system’s sendmail.

Example

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.

trail components add <REFERENCE>

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

trail components add trailbase/auth_ui

trail components add https://example.com/component.wasm

trail components add ./my_component.wasm
trail components add ./components.zip

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

components remove

Remove/delete a WASM component.

trail components remove <REFERENCE>

string

required

Component reference: name or local path. URLs are not supported for removal.

This permanently deletes the component files from disk.

trail components remove trailbase/auth_ui

trail components remove ./my_component.wasm

components list

List available first-party components.

trail components list

Example output:

Components:

trailbase/auth_ui

components installed

List installed components with their interfaces.

trail components installed

Example output:

./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.

trail components update

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

Example Output

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

Start TrailBase for the first time

# Initialize with default settings
trail run

# Server starts on http://localhost:4000
# Data directory created at ./traildepot/

Create your first admin user

# 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

Create and apply a database migration

# 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

Install a WASM component

# List available components
trail components list

# Install a component
trail components add trailbase/auth_ui

# Verify installation
trail components installed

REST APIs

Client SDKs

CLI Reference

Overview

Global Options

Commands

run

schema

openapi

openapi print

openapi run

migration

admin

admin list

admin promote

admin demote

user

user add

user delete

user change-password

user change-email

user verify

user invalidate-session

user mint-token

user import

email

components

components add

components remove

components list

components installed

components update

Exit Codes

Environment Variables

Common Workflows

​Overview

​Global Options

​Commands

​run

​schema

​openapi

​openapi print

​openapi run

​migration

​admin

​admin list

​admin promote

​admin demote

​user

​user add

​user delete

​user change-password

​user change-email

​user verify

​user invalidate-session

​user mint-token

​user import

​email

​components

​components add

​components remove

​components list

​components installed

​components update

​Exit Codes

​Environment Variables

​Common Workflows

Overview

Global Options

Commands

run

schema

openapi

openapi print

openapi run

migration

admin

admin list

admin promote

admin demote

user

user add

user delete

user change-password

user change-email

user verify

user invalidate-session

user mint-token

user import

email

components

components add

components remove

components list

components installed

components update

Exit Codes

Environment Variables

Common Workflows