# 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`:
```sh
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`:
```sh
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](../../docs/database-migrations.md) and the
[migration test matrix](./tests/README.md).
`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:
```sh
# 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`](../rustauth-telemetry/README.md).
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`](../rustauth-telemetry/README.md#quick-start)
(runtime, environment, and anonymized config detection). The command-specific
event follows immediately afterward.
| *(bootstrap)* | — | `init` | — (no `outcome`; see [`rustauth-telemetry`](../rustauth-telemetry/README.md#quick-start)) |
| `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
| `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](../rustauth-telemetry/README.md#environment).
### 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:
```sh
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](./UPSTREAM.md).
## Links
- [Root README](../../README.md)
- [Repository](https://github.com/salasebas/rustauth)