CLI
Build and run the Go better-iam command, which has the same commands, flags, and exit codes as the TypeScript CLI and reads better-iam.json, and ship a project CLI with your own commands.
The Go module ships the better-iam command as a single static binary. It is a port of the TypeScript CLI with the
same commands, flags, help, and exit codes: migrations, bootstrap, scheduled jobs, audit and storage operations,
diagnostics, configuration as code, the API caller, and saved sessions. Because it runs the Go server in process, it
needs no Node.js on the machine, which suits containers, cron hosts, and CI images.
The CLI concepts page explains how the CLI works and the CLI reference lists every command and flag; both apply to the Go binary. This page covers what is specific to Go.
Install
No tagged release exists yet, so build the binary from a checkout of the repository:
git clone https://github.com/Better-IAM/better-iam.git
cd better-iam/go
go build -o better-iam ./cmd/better-iam
./better-iam helpOnce the module is tagged, go install github.com/Better-IAM/better-iam/go/cmd/better-iam@latest installs it, and
release binaries for Linux, macOS, and Windows are planned for each GitHub release.
Configuration
The TypeScript CLI imports a JavaScript configuration module. A Go program cannot run JavaScript, so the Go CLI reads
better-iam.json, the JSON configuration every implementation shares, and refuses a .ts or .mjs file with
CONFIG_LOAD_FAILED. It looks for the configuration in the same order as the TypeScript CLI:
--config PATHBETTER_IAM_CONFIG- The nearest
better-iam.jsonorbetter-iam.config.jsonin the working directory or a parent, stopping at the repository root or the home directory BETTER_IAM_DATABASE_URLandBETTER_IAM_SECRETwith no file (postgres://…,sqlite:./iam.db, orlibsql://…)
better-iam init writes a starter better-iam.json for SQLite, PostgreSQL (--database postgres), or libSQL
(--database libsql), with the secret read from BETTER_IAM_SECRET. With --typescript it writes the
better-iam.config.ts module a TypeScript application loads instead. It never overwrites an existing file.
better-iam init
export BETTER_IAM_SECRET="$(better-iam secret)"
better-iam migrate
BETTER_IAM_ROOT_EMAIL=root@example.com BETTER_IAM_ROOT_PASSWORD='…' better-iam bootstrapThe optional cli member of better-iam.json sets flag defaults per command ("*" applies to every command with
that flag):
{
"store": { "kind": "postgres", "url": { "env": "DATABASE_URL" } },
"secret": { "env": "BETTER_IAM_SECRET" },
"baseURL": "https://app.example.com",
"cli": { "defaults": { "sweep": { "retention-days": 30 } } }
}Your Go application can load the same file with cli.LoadConfig; see
Go: Create the instance.
Common commands
better-iam doctor --strict # check the database, schema, secrets, and scheduled jobs
better-iam outbox # deliver pending email, SMS, and webhooks (schedule it)
better-iam sweep && better-iam purge # expire old records (schedule them)
better-iam audit-verify --tenant ten_123 # recompute a tenant's audit hash chain
better-iam config-plan --tenant ten_123 --input access.json --fail-on-driftConfiguration commands open the database and run with no credential. Token commands (whoami, can, api,
config-apply, and others) act as BETTER_IAM_TOKEN or a saved session, in process through the configuration or
against a running server with --url, and are authorized and audited like console operations.
better-iam login --url https://iam.example.com --org acme --email me@acme.test
better-iam api roles.create name=Reader permissions:='["documents:read"]' --url https://iam.example.com
better-iam api identities.list limit:=5 --query "[].email"login keeps sessions in the same credentials file as the TypeScript CLI (BETTER_IAM_CREDENTIALS, else
%APPDATA%\better-iam\credentials.json on Windows or ~/.config/better-iam/credentials.json), so either binary can
use a profile the other saved. better-iam help lists every command, and better-iam help --json prints the
manifest for tools.
Exit codes match the TypeScript CLI: 0 on success, 2 for a usage mistake, 1 otherwise. Failures print
CODE: message on stderr; set BETTER_IAM_DEBUG=1 for details of unexpected errors.
Add project commands
cli.CreateCli builds a program with the built-in commands plus your own, declared with cli.DefineCommand. Your
commands get the same flag parsing, help, configuration loading, and output formatting. Ship the result as your own
binary:
package main
import (
"context"
"github.com/Better-IAM/better-iam/go/cmd/better-iam/cli"
"github.com/Better-IAM/better-iam/go/core"
)
var countPeople = cli.DefineCommand(cli.CommandSpec{
Name: "count-people",
Group: "Project",
Summary: "Print how many people an organization has",
Target: "config", // loads better-iam.json; runs with no credential
Flags: []cli.FlagSpec{
{Name: "tenant", Type: "string", Value: "TENANT_ID", Required: true, Description: "The organization"},
},
Run: func(ctx context.Context, c *cli.CommandContext) (any, error) {
instance, err := c.Iam(ctx)
if err != nil {
return nil, err
}
people, err := instance.Store.Find(ctx, "identities", core.NewObject("tenantId", c.Flags.String("tenant")), nil)
if err != nil {
return nil, err
}
return core.NewObject("tenantId", c.Flags.String("tenant"), "people", float64(len(people))), nil
},
})
func main() {
cli.RunBinary(cli.CreateCli(cli.CreateCliOptions{
Commands: []*cli.CommandSpec{countPeople},
}))
}go run ./cmd/acme-iam count-people --tenant ten_123 --format tableTargetis"config"for a deployment operation (c.Iam(ctx)opens the instance),"token"for a command that acts as the current token (c.Api(ctx, cli.ApiOptions{})returns a transport, local or remote), or empty for a command that needs neither.- The result you return is printed with
--format(json,compact,table) and--queryapplied. - Configuration from code:
cli.CreateCliOptions.LoadModulesupplies configuration modules from Go (options, a ready instance, or a factory, plus commands and CLI defaults) for deployments that cannot be described in JSON, such as ones with custom callbacks.
cli.RunCli(ctx, argv, io) runs one command line from code and returns its error, which tests use to drive commands
with their own *cli.CliIO. cli.Manifest() returns the machine-readable description of every built-in command.
Related
Better IAM is created by Sean Filimon
Last updated
Typed clientbeta
Call any Better IAM server over HTTP from Go with client.New, with a method per route, generated request and answer types, bearer or cookie authentication, and typed errors.
Features
Every Better IAM feature module with one line on what it adds, the API group, server option, or package that turns it on, and a link to its page.