authctl

Operator CLI for auth.anmho.com service OAuth clients and resource servers.

Install

Install or update authctl from npm:

npm install -g @anmho/authctl
npm update -g @anmho/authctl
authctl doctor --json
authctl --local doctor --json

For local checkout development, link the CLI into your shell:

cd /Users/andrewho/repos/projects/auth

bun run authctl:link
hash -r
which authctl
authctl --local doctor --json
authctl --local clients list --json

The linked binary resolves tools/authctl/src/index.ts from this repo, so code edits are picked up without publishing to npm. Use the root convenience script only when you deliberately do not want the shell link:

bun run authctl:local -- clients list --json

Remove the local link with:

bun run authctl:unlink

Operator Setup

Production authctl calls https://auth.anmho.com/internal through Cloudflare Access using a service token stored in Vault at secret/prod/apps/auth/authctl/cloudflare-access.

Credential resolution order: CLI flags → environment variables → Vault (when vault is available and AUTHCTL_DISABLE_VAULT is not set) → defaults.

Run auth operations from this checkout:

cd /Users/andrewho/repos/projects/auth

# Optional if you already use home ~/.zshrc vault-env (loads the same three vars):
# vault-env

export AUTH_INTERNAL_BASE_URL="$(vault kv get -mount=secret -field=AUTH_INTERNAL_BASE_URL prod/apps/auth/authctl/cloudflare-access)"
export CLOUDFLARE_ACCESS_SERVICE_TOKEN_CLIENT_ID="$(vault kv get -mount=secret -field=CLOUDFLARE_ACCESS_SERVICE_TOKEN_CLIENT_ID prod/apps/auth/authctl/cloudflare-access)"
export CLOUDFLARE_ACCESS_SERVICE_TOKEN_CLIENT_SECRET="$(vault kv get -mount=secret -field=CLOUDFLARE_ACCESS_SERVICE_TOKEN_CLIENT_SECRET prod/apps/auth/authctl/cloudflare-access)"

authctl never prints stored client secrets from list/get commands. Create and rotate print a new client secret once, plus the Vault command for storing it.

Troubleshooting: See authctl operator access (401 from Cloudflare vs missing credentials, vault-env, --local).

Doctor

Check production config:

authctl doctor --json

Expected from this machine when Vault is available: ok is true, base_url is https://auth.anmho.com/internal, and both has_access_client_id and has_access_client_secret are true.

If Vault/env credentials are unavailable, or if AUTHCTL_DISABLE_VAULT=1 is set, ok is false and the findings array includes the exact Vault export commands for secret/prod/apps/auth/authctl/cloudflare-access.

Local dev does not need Cloudflare Access credentials:

authctl --local doctor --json

Resource Servers

Resource servers are the authctl-owned API/resource inventory. OAuth clients must target an active resource server for their stage before token issuance can succeed.

Create or update a resource server:

authctl resource-servers upsert \
  --resource-server billing \
  --scope invoices:read \
  --scope invoices:write \
  --stage prod \
  --json

List, get, and disable resource servers:

authctl resource-servers list --stage prod --json
authctl resource-servers get --resource-server billing --stage prod --json
authctl resource-servers delete --resource-server billing --stage prod --json

Use --force when disabling a resource server that still has active OAuth clients:

authctl resource-servers delete --resource-server billing --stage prod --force --json

OAuth Clients

List clients:

authctl clients list --json

Create a service OAuth client:

authctl clients create \
  --client-app agent \
  --client-identity server \
  --resource-server billing \
  --scope invoices:read \
  --stage prod \
  --yes \
  --json

The command returns a vault_command like:

vault kv put -mount=secret prod/apps/agent/server/oauth-clients/billing client_id='agent-server-billing-prod' client_secret='...'

Get, rotate, and revoke:

authctl clients get --client-id agent-server-billing-prod --json

authctl clients rotate \
  --client-id agent-server-billing-prod \
  --vault-path prod/apps/agent/server/oauth-clients/billing \
  --yes \
  --json

authctl clients revoke \
  --client-id agent-server-billing-prod \
  --yes \
  --json

Bulk revoke active clients for a resource server:

authctl clients revoke --resource-server billing --stage prod --yes --json

Smoke

Local end-to-end smoke test:

bun run dev:smoke

dev:smoke starts the local database and API, then delegates the client/token proof to authctl --local smoke. The CLI command can also target any configured server directly:

authctl --local smoke --json
authctl smoke --json
authctl --base-url http://localhost:8787/internal smoke --json

Release

npm publishing for @anmho/authctl and @anmho/auth-schemas is handled by GitHub Actions trusted publishing through .github/workflows/publish-authctl.yml. The workflow publishes only versions that do not already exist on npm, so a normal version bump on main is enough to update the installable CLI.

Configure npm trusted publishers:

@anmho/authctl       -> anmho/auth / publish-authctl.yml
@anmho/auth-schemas -> anmho/auth / publish-authctl.yml

Version packages/schemas/package.json and tools/authctl/package.json together. tools/authctl/package.json must depend on the exact schema package version being published.