CLI
The better-iam command line built in Rust, with the same 60 commands, flags, output formats, and exit codes as the npm CLI, configured by better-iam.json, and extensible with project commands.
The better-iam-cli crate builds a native better-iam binary: the Rust counterpart of
@better-iam/cli. It has the same commands, flags, help text, output formats
(--format json|compact|table, --query), and exit codes, and it works on the same database, so you can run the
scheduled jobs of a TypeScript deployment from the Rust binary and the other way around. It needs no Node.js runtime,
which suits containers and hosts that run only Rust or Go services.
Not on crates.io yet
Install the binary from a checkout of the repository. See the Rust overview for the current parity status.
Install
# from a checkout of the repository
cargo install --path crates/cli # SQLite and PostgreSQL
cargo install --path crates/cli --features libsql # also libsql:// and file: databases
better-iam --versionThe binary is named better-iam, like the npm CLI's bin. When both are installed, the one earlier on your PATH
wins; better-iam doctor reports which one ran ("runtime": "rust better-iam-cli 0.3.1").
Quick start
better-iam init # writes better-iam.json for SQLite
export BETTER_IAM_SECRET=$(better-iam secret) # keep it stable: it seals stored secrets
better-iam migrate
BETTER_IAM_ROOT_EMAIL=root@example.com BETTER_IAM_ROOT_PASSWORD='a long passphrase' better-iam bootstrap
better-iam doctorbetter-iam init --database postgres (or libsql) writes a configuration that reads the database URL from the
environment instead. better-iam help lists every command, better-iam help <command> shows one command's flags and
examples, and better-iam help --json prints the machine-readable manifest.
Configuration
This is the one real difference from the npm CLI. The npm CLI imports better-iam.config.mjs, a JavaScript module;
the Rust CLI reads the standalone configuration every implementation shares, better-iam.json
(From better-iam.json describes the format). It looks for it in this
order:
--config PATH- the
BETTER_IAM_CONFIGenvironment variable - the nearest
better-iam.jsonin the working directory or a parent, up to the repository root or your home directory (files another user could have planted are skipped) - no file:
BETTER_IAM_DATABASE_URLandBETTER_IAM_SECRETalone
With environment variables only, BETTER_IAM_DATABASE_URL is postgres://..., sqlite:PATH (or a path ending in
.db), or libsql://... / file:... (with the libsql feature; BETTER_IAM_DATABASE_TOKEN authenticates). The
optional BETTER_IAM_PREVIOUS_SECRETS (comma-separated), BETTER_IAM_BASE_URL, BETTER_IAM_BASE_PATH, and
BETTER_IAM_TRUSTED_ORIGINS complete it.
The module's cli export becomes a cli member of the JSON file, holding flag defaults per command (or * for every
command that has the flag):
{
"store": { "kind": "sqlite", "path": "./better-iam.db" },
"secret": { "env": "BETTER_IAM_SECRET" },
"baseURL": "https://iam.example.com",
"cli": { "defaults": { "sweep": { "retention-days": 30 }, "*": { "format": "compact" } } }
}A flag on the command line wins over its environment variable, which wins over the cli default.
How it matches the npm CLI
npm better-iam | Rust better-iam | |
|---|---|---|
| Commands | 60 built-in commands | The same 60, with the same names, flags, and help |
| Output | --format json|compact|table, --query | The same |
| Exit codes | 0 on success, 2 for a usage mistake, 1 otherwise; vault-run exits with its command's status | The same |
| Configuration | better-iam.config.mjs (or .js, .ts, .mts, .cjs) | better-iam.json |
init | Writes a module; --typescript writes better-iam.config.ts | Writes better-iam.json; --typescript is refused |
config-plan, config-apply, config-validate input | JSON or a JavaScript/TypeScript module | JSON |
config-export --output | .json, .ts, or .mjs | The same (.ts and .mjs for Node.js projects) |
| Project commands | The config module's commands export | Your own binary built with create_cli |
Saved sessions (login) | ~/.config/better-iam/credentials.json (%APPDATA% on Windows) | The same file and BETTER_IAM_CREDENTIALS override |
| libSQL | @better-iam/adapter-libsql installed next to the CLI | The libsql feature |
Because the commands are the same, the CLI reference documents both: every flag, environment
variable, and example there applies to the Rust binary with --config better-iam.json in place of a module path. The
groups are the same too:
- Setup:
init,migrate,bootstrap,recover-root,doctor,secret,ssh-host-enroll - Operations (the scheduled jobs):
outbox,purge,sweep,digest,remind,reconcile,close-certifications,monitor-invariants,detect-threats,rotate-secrets, thebilling-*jobs,ssh-host-sync,ssh-sweep,vc-sweep,compliance-evaluate, and thevault-*maintenance jobs - Audit:
audit-verify,audit-export,audit-prune,audit-archive,audit-verify-archive - Storage:
store-export,store-import,store-copy - Access (as a signed-in token):
config-export,config-plan,config-apply,config-validate,analyze,report,mine-roles,check-invariants,whoami,can,explain,who-can,spend,ssh-cert,vault-get,vault-put,vault-run - API and session:
api,login,logout,profiles,token - Shell:
completion
better-iam login --url https://iam.example.com --org acme --email me@acme.test
better-iam api identities.list limit:=5 --format table
better-iam config-plan --tenant ten_123 --input iam/tenant.json --fail-on-drift
better-iam store-copy --config sqlite.json --target-config postgres.jsonSchedule the jobs
The operation commands are the same jobs the npm CLI runs, against the same database, so a deployment can schedule them with either binary. A container that already runs a Rust server can run them with the Rust binary:
*/1 * * * * better-iam outbox --config /etc/better-iam/better-iam.json
0 * * * * better-iam sweep --config /etc/better-iam/better-iam.json
0 3 * * * better-iam purge --config /etc/better-iam/better-iam.jsonScheduling the job commands lists every job and how often to run
it. Give the CLI the same BETTER_IAM_SECRET and BETTER_IAM_PREVIOUS_SECRETS as the servers.
Project commands
A project ships its own commands by building its own binary on the library: create_cli takes the built-in commands
plus yours, with the same parsing, help, configuration loading, and output. It replaces the commands export of the
npm config module.
[dependencies]
better-iam-cli = { path = "../better-iam/crates/cli" }
serde_json = "1"use better_iam_cli::{CommandTarget, CreateCliOptions, FlagSpec, create_cli, define_command};
use serde_json::json;
fn main() {
let seed = define_command("seed", "Create the demo organization", |context| async move {
let iam = context.iam()?; // the instance better-iam.json describes
let slug = context.flags.string("slug").unwrap_or("demo").to_owned();
let _ = iam; // create the organization with iam.api.* here
Ok(Some(json!({ "created": slug })))
})
.target(CommandTarget::Config)
.flag("slug", FlagSpec::string("Organization slug").default_text("demo"));
let cli = create_cli(CreateCliOptions { commands: vec![seed], ..Default::default() });
std::process::exit(better_iam_cli::run_binary(std::env::args().skip(1).collect(), Some(cli)));
}cargo run --bin iam -- seed --slug acme
# { "created": "acme" }define_command(name, summary, run)takes an async closure that receives aCommandContext. ReturningOk(Some(value))prints the value with--formatand--queryapplied;Ok(None)prints nothing..target(...)says what the command needs:CommandTarget::Config(the configuration and database,context.iam()),CommandTarget::Token(a saved session or token,context.api(...)), orCommandTarget::None..flag(name, FlagSpec::string(...)),FlagSpec::integer, andFlagSpec::booleandeclare flags, with.required(),.env("NAME"),.default_text(...),.choices(...),.min(...)and.max(...);.arg(ArgSpec::new(...))declares positional arguments. Thecli.defaultsofbetter-iam.jsonapply to project commands too.run_binaryruns the program like thebetter-iambinary does: it starts its own tokio runtime, somainneeds no#[tokio::main], printsCODE: messageon failure, and returns the exit status.CreateCliOptions { builtins: Some(false), .. }ships only your commands.
To run a command from Rust code, such as a test, call cli.run(&argv, Some(io)).await on the program, or
better_iam_cli::run_cli(&argv, None) for the built-in commands; both return CliResult<()>, whose CliError
carries the error code.
The standalone server binary
The better-iam binary does not serve HTTP, as the npm CLI does not. The better-iam-server binary from the
better-iam-server crate does: it reads the same better-iam.json, migrates, and serves the API. See
The standalone server.
Related
Better IAM is created by Sean Filimon
Last updated
Typed clientbeta
Call a Better IAM server from Rust with better-iam-client, a typed method per route with generated request and result types, CSRF headers, bearer tokens, structured errors, a session store, and device proofs.
Gobeta
Run the Better IAM server natively in Go. Install the module, create the instance from options or better-iam.json, run migrations, serve the http.Handler, and call the API in process.