BetterIAM
Go

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.

betagithub.com/Better-IAM/better-iam/go/cmd/better-iammain.gocli.goconfig.goframework.goprofiles.gocommands_setup.gocli_test.go

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 help

Once 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:

  1. --config PATH
  2. BETTER_IAM_CONFIG
  3. The nearest better-iam.json or better-iam.config.json in the working directory or a parent, stopping at the repository root or the home directory
  4. BETTER_IAM_DATABASE_URL and BETTER_IAM_SECRET with no file (postgres://…, sqlite:./iam.db, or libsql://…)

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 bootstrap

The optional cli member of better-iam.json sets flag defaults per command ("*" applies to every command with that flag):

better-iam.json
{
  "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-drift

Configuration 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:

cmd/acme-iam/main.go
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 table
  • Target is "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 --query applied.
  • Configuration from code: cli.CreateCliOptions.LoadModule supplies 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.

Was this page helpful?

Better IAM is created by Sean Filimon

Last updated

On this page