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:

--data-dir

string

default:"./traildepot"

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

--public-url

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

--version

boolean

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

Commands

run

Starts the HTTP server.

trail run [OPTIONS]

-a, --address

string

default:"localhost:4000"

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

--admin-address

string

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

--public-dir

string

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

--spa

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

--runtime-root-fs

string

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

--geoip-db-path

string

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

--dev

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

--demo

boolean

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

--stderr-logging

boolean

default:"false"

Enable logging to stderr.

--cors-allowed-origins

string[]

default:"*"

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

--runtime-threads

number

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

trail run

schema

Export JSON Schema definitions for a table/API.

trail schema <API_NAME> [OPTIONS]

api

string

required

Name of the table to infer the JSON Schema from.

--mode

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

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]

-a, --address

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]

suffix

string

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

--db

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

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	[email protected]	2024-01-15T10:30:00Z	2024-03-07T14:22:00Z

admin promote

Promotes a user to admin.

trail admin promote <USER>

user

string

required

User identifier, either email address or UUID.

Example

trail admin promote [email protected]
trail admin promote 550e8400-e29b-41d4-a716-446655440000

admin demote

Demotes an admin user to normal user.

trail admin demote <USER>

user

string

required

User identifier, either email address or UUID.

Example

trail admin demote [email protected]

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.

password

string

required

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

Example

trail user add [email protected] SecureP@ssw0rd

user delete

Delete a user.

trail user delete <USER>

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 [email protected]

user change-password

Change a user’s password.

trail user change-password <USER> <PASSWORD>

user

string

required

User identifier, either email address or UUID.

password

string

required

New password to set for the user.

Example

trail user change-password [email protected] NewP@ssw0rd123

user change-email

Change a user’s email address.

trail user change-email <USER> <NEW_EMAIL>

user

string

required

User identifier, either email address or UUID.

new_email

string

required

New email address to set for the user.

Example

trail user change-email [email protected] [email protected]

user verify

Change a user’s verification state.

trail user verify <USER> [VERIFIED]

user

string

required

User identifier, either email address or UUID.

verified

boolean

default:"true"

User’s verification state to set.

trail user verify [email protected] true

user invalidate-session

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

trail user invalidate-session <USER>

user

string

required

User identifier, either email address or UUID.

Example

trail user invalidate-session [email protected]

user mint-token

Mint an auth token for the given user.

trail user mint-token <USER>

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]

--auth0-json

string

Path to Auth0 exported users as ND JSON file.

-n, --dry-run

boolean

default:"false"

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

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

email

Programmatically send emails using the configured email provider.

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

--to

string

required

Receiver address (e.g., [email protected]).Environment variable: TO

--subject

string

required

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

--body

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 [email protected] \
  --subject "Welcome to TrailBase" \
  --body "Thank you for joining!"

components

Manage WASM components.

components add

Add a new WASM component.

trail components add <REFERENCE>

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

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

components remove

Remove/delete a WASM component.

trail components remove <REFERENCE>

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

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 [email protected] SecurePassword123

# Promote to admin
trail admin promote [email protected]

# Verify the user
trail user verify [email protected] 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

Build docs developers (and LLMs) love

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

Build docs developers (and LLMs) love

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