rustauth-cli 0.2.0

Command-line tools for RustAuth.
Documentation

rustauth-cli

Command-line tools for RustAuth.

What It Is

rustauth-cli provides local developer tooling for RustAuth projects. The published package exposes the rustauth binary and cargo-style aliases.

What It Provides

  • Secret generation.
  • Project diagnostics.
  • Workspace and package information.
  • Schema and migration planning output.
  • Project initialization helpers.
  • Plugin inspection and changes for official RustAuth plugins.
  • Shell completion generation.

Quick Start

These commands work in any directory and do not need an rustauth.toml:

rustauth secret --bytes 32              # generate a signing secret
rustauth plugins list                   # list official plugins
rustauth schema print --dialect sqlite  # print the base RustAuth schema
rustauth generate --adapter kysely --dialect sqlite --output auth.sql --yes
rustauth doctor                         # diagnose the environment

Without a config, doctor reports what is missing (including the absent rustauth.toml) and schema print emits the default schema, so the CLI is useful before any project setup.

To create a project and unlock the config-bound workflow, run rustauth init first. It writes rustauth.toml, syncs .env.example, and creates or updates .env in the current directory. Missing keys are merged in without overwriting values that are already present; a new .env is copied from .env.example and uses placeholder secrets unless you pass --seed-secrets to generate a signing secret for local development. The following commands read rustauth.toml:

rustauth init                # rustauth.toml + .env.example + .env
rustauth init --seed-secrets # same, but a new .env gets a generated RUSTAUTH_SECRET
rustauth doctor --production # config-aware production readiness checks
rustauth db generate         # generate a migration from the configured schema
rustauth db migrate --yes    # apply pending migrations (non-interactive)

Database migrations are CLI-only: applications should run rustauth db migrate before serving traffic instead of calling a runtime helper on RustAuth. See docs/database-migrations.md and the migration test matrix.

rustauth db status, rustauth db generate, and rustauth db migrate support database.adapter = "sqlx" (sqlite, postgres, mysql) as well as tokio-postgres and deadpool-postgres (postgres only). Use the same adapter in rustauth.toml that your application runs.

The CLI ships with no adapter or enterprise plugin features enabled by default. Enable the features that match your rustauth.toml when installing or building:

# sqlx (sqlite, postgres, mysql) — most common
cargo install rustauth-cli --features sqlx

# native Postgres adapters
cargo install rustauth-cli --features tokio-postgres
cargo install rustauth-cli --features deadpool-postgres

# official plugin schema planning (admin, jwt, organization, …)
cargo install rustauth-cli --features plugins

# enterprise extension plugins (enable what your config uses)
cargo install rustauth-cli --features passkey,sso,scim,stripe,oauth-provider

# everything (adapters + enterprise schema plugins + telemetry)
cargo install rustauth-cli --features full
cargo install rustauth-cli --all-features

rustauth db generate and rustauth db migrate require the CLI feature that matches each enabled plugin (for example passkey for [plugins] enabled = ["passkey"]). Rebuild with --features full to restore the previous always-linked enterprise surface.

The CLI is intentionally transparent: it inspects the current Rust workspace and prints or writes RustAuth configuration/migration output without hiding the Rust code that owns your application behavior. generate --adapter kysely and generate --adapter sqlx are SQL-only Better Auth compatibility paths; Prisma and Drizzle schema files are not generated by this Rust CLI.

Environment variables

Before running config-backed commands, the CLI loads .env and .env.local without overriding variables already set in the process environment. When --config points at a file outside the project root layout, files next to that config are loaded first, then files in --cwd (weaker to stronger: config/.env, config/.env.local, <cwd>/.env, <cwd>/.env.local).

Telemetry

generate and migrate (including the db generate / db migrate aliases) can emit opt-in telemetry through rustauth-telemetry. Other CLI commands do not publish telemetry events today.

Telemetry is off by default. Nothing leaves the process until you opt in and provide a collector endpoint (or a custom sink wired by your host application). The RustAuth maintainers do not receive CLI telemetry unless you point an endpoint at their infrastructure.

Commands and events

Every opted-in generate / migrate run first emits the shared telemetry bootstrap event init from create_telemetry (runtime, environment, and anonymized config detection). The command-specific event follows immediately afterward.

Command Aliases Event type Typical outcome values
(bootstrap) — init — (no outcome; see rustauth-telemetry)
generate db generate cli_generate generated, no_changes, aborted, overwritten, unsupported_adapter, unsupported_database
migrate db migrate cli_migrate migrated, no_changes, dry_run, aborted, unsupported_adapter, unsupported_database

Each command event includes an outcome string describing the CLI result and a Better Auth-shaped config snapshot derived from rustauth.toml (adapter, database provider, enabled plugins, and anonymized feature flags). Adapter or database errors may add top-level adapter / database fields before the config block.

Environment variables

Variable Purpose
RUSTAUTH_TELEMETRY Master switch. true/1 opts in; false/0 is a hard opt-out. When unset, telemetry stays off for CLI commands.
RUSTAUTH_TELEMETRY_DEBUG Print JSON events to stderr instead of POSTing (useful for local inspection).
RUSTAUTH_TELEMETRY_ENDPOINT Collector URL. Required before events are sent over the network.

Enablement precedence, test suppression, and transport details are documented in the rustauth-telemetry README.

Payload and redaction

CLI telemetry follows the same anonymized config snapshot as server-side RustAuth telemetry:

  • Included: adapter name, database provider, plugin IDs, boolean/count summaries of configured features (email/password, sessions, rate limits, and similar flags).
  • Excluded: signing secrets, database URLs or connection strings, base URLs, OAuth client credentials, environment variable names from [security], and other concrete deployment identifiers.

Inspect redacted output locally with debug mode:

RUSTAUTH_TELEMETRY=true \
RUSTAUTH_TELEMETRY_DEBUG=true \
RUSTAUTH_TELEMETRY_ENDPOINT=http://127.0.0.1:9999/collect \
rustauth db generate --yes

Opt-out

For local shells and CI, the simplest opt-out is to leave RUSTAUTH_TELEMETRY unset or set RUSTAUTH_TELEMETRY=false. That overrides any application-level telemetry settings inherited from the environment.

Status

Experimental beta. Commands, flags, generated output, and workspace detection may change before stable release.

Better Auth compatibility

Developer CLI and local schema/migration tooling aligned with Better Auth 1.6.9 where it matters; RustAuth is not a line-by-line port.

For command-level parity, test counts, intentional differences, and known gaps, see UPSTREAM.md.

Links