AuthDB Management CLI

The standalone server is maintained by authdb. Its portal root can be used as this client's base_url; authentication and management protocols remain unchanged.

Ownership and Contracts

cmd/authdbctl owns application paths, configuration discovery, flags/env, terminal input, management commands, retry decisions, and output. Use authentication-client to change the importable login protocol or opaque credential-file behavior. Keep CLI and admin API dependencies out of pkg/authclient. connect authenticates through /login even when the admin API is disabled.

Preserve AUTHDBCTL_* environment names and ~/.config/authdbctl defaults. Explicit flags override environment; YAML token_path overrides the path flag. Freshly acquired credentials replace the in-memory cache only after a successful file save. A failed login/save must preserve previously usable credentials. The embedded authclient.Config accepts explicit YAML refresh_transport: body for native login to a refresh realm with body transport enabled. The omitted cookie mode and existing flags/env precedence remain unchanged. Save the whole new credential bundle, including refresh/session metadata, without merging an old refresh token. Initial native login does not imply automatic renewal. Unavailable transport fails without retrying or overwriting the cache. The authentication-client contract owns the public parser and transport errors.

Config in cmd/authdbctl/config.go embeds authclient.Config and adds CLI-owned TokenPath and the compatibility CookieName field. The reusable login settings have pkg/authclient/parser; CLI file discovery, path precedence, and command-specific settings still use local YAML/flag handling with no dedicated public parser. Document that legacy boundary when extending CLI configuration; do not describe the login parser as covering the whole command configuration.

Keep one buffered reader per wrapper for plain identity input; creating readers for consecutive prompts can discard piped lines. Hidden prompts use a real terminal, with terminal state owned by the caller and restored on completion, error, or context timeout. The raw-mode line editor handles Ctrl-C/Ctrl-D as EOF. A pending read must not change OS terminal settings after cancellation. Prompt cancellation ends the command; do not start another prompt while that read is pending. Do not move terminal IO into the reusable authentication package.

Management requests attach opaque credentials and reuse the cache. Access denial may cause a fresh login only when another attempt remains. System messages have token attachment disabled and must not trigger login. Validate management HTTP 200 bodies as JSON objects and reject status: failure; a failed mutation must return an error without retrying. Malformed responses, including null, must not produce a successful command exit. Preserve the original successful JSON body for output, including generated credentials the command is meant to return. The shared HTTP browser caps all responses at 16 MiB, including chunked bodies; an oversized response is deterministic and must fail without retrying. Never put response bodies or configured secrets in error diagnostics.

Marshal realm/user fields as JSON rather than interpolating strings. A user update selects exactly one operation; reject absent or conflicting selections before configuration, login, or mutation. Hash generation may print the new hash and intentionally generated API key, but must not print supplied password fragments. Report encryption-key setup failures as errors.

Password generation supports --algorithm bcrypt|argon2; bcrypt remains the default. Argon2 uses --memory (KiB), --iterations and --parallelism; reject --cost with Argon2 and Argon2 options with bcrypt. generate_password_hash.go encodes the flags for the public password parser and passes its typed result to identity.NewPasswordWithConfig, then prints Password.EncodedHash(). --db-path selects password policy without dropping the requested hash options. Use Database.CheckPasswordPolicyCompliance so unrelated username constraints cannot reject generation. Check the normalized password's length, including minimum/maximum boundaries, in unit and executable tests. See password hashing contracts for formats, defaults, resource bounds and library integration.

Test Boundaries

Keep corresponding tests for every Go change, including CLI helpers. The tests are in the default suite, with no external accounts or services:

• authentication_test.go: authentication adapter, credential precedence, cache reuse, and login/retry behavior using scripted HTTP responses.
• commands_test.go: every management action, exact method/path/header/JSON payload, escaped realm names, response errors, configuration failures, and CSV/table output. Fresh flag sets prevent shared urfave flag state.
• failures_test.go: configuration and filesystem failures, failed credential saves, transport/read errors, malformed management responses, reauthentication failures, retry limits, and cancellation.
• utility_commands_test.go: bcrypt verification of generated hashes, password policy/cost errors, system-key permissions, and encrypted request/response round trips without access-token authentication.
• generate_password_hash_test.go: Argon2 generation/defaults, independent hash verification, clean option rejection and the executable generation/import/login journey called by TestE2EAuthdbctl/argon2_password_hash.
• terminal_test.go and cmd/authdbctl/testdata/terminal.py: real pseudo-terminal input, hidden echo, MFA choice mapping, EOF/interruption, and timeout restoration. Python 3's standard library supplies the PTY on Unix; missing Python is a failure there. Only PTY-dependent cases skip on Windows. Close the broker before its slave descriptor so pending reads unblock during cleanup.
• e2e_test.go: build the real race-instrumented executable once, then run subprocesses with isolated homes and sanitized AUTHDBCTL_* environment. Use a real authn.Portal and temporary local identity database. Exercise configured password/TOTP/API keys, piped identity, interactive password/TOTP and combined MFA, rejected credentials and unsupported MFA choices, config routing, help/version, missing flags, cached authentication and re-login, and the complete management lifecycle. Assert on-disk identity changes, command exit status, token permissions, and authentication of saved tokens through /whoami using a separate client.

Legacy executable E2E uses loopback HTTP with explicitly insecure fixture cookies. transport_e2e_test.go runs the actual executable with parser-produced YAML against a real refresh portal over a loopback relay. The relay's outbound TLS client trusts the test portal; this avoids OS trust-store mutations on macOS. It verifies password/TOTP native login, repeated connect, complete saved credentials, and cache preservation when body transport is unavailable. This fixture does not establish direct CLI custom-CA configuration. pkg/authclient independently covers direct real TLS and browser-jar isolation. Enable the admin API only for management cases. Assert authentication-only cases issue only login requests. Never use live credentials or a real user's config/cache. WebAuthn rejection tests do not establish hardware assertion support.

Capture prompt output when testing functions directly. An unterminated prompt can absorb Go's test event markers and make the structured report incomplete even when the Go process exits successfully. Keep failure reports until the corrected run has its own evidence.

Validation

make test TEST_DIR='./cmd/authdbctl' COVERAGE_DIR='.coverage/authdbctl'
make test TEST_DIR='./cmd/authdbctl' TEST='^TestE2EAuthdbctl$' COVERAGE_DIR='.coverage/authdbctl-e2e'
make test TEST_DIR='./pkg/authclient' COVERAGE_DIR='.coverage/authclient' MINIMUM_COVERAGE=100
make ci-check
go vet ./...

Report measured CLI statement coverage separately from executable E2E results: the subprocess binary is not included in the parent Go test coverage profile. Do not claim the CLI is 100% covered because its executable passes E2E tests. The reusable package retains its own explicit 100% gate. Inspect tested's final outcome and incomplete-test count, not only the Go process status.