@x12i/authx-token-cli

Terminal CLI for AuthX Token Infrastructure. Talks to the HTTP API (token-service) — register apps, issue tokens, verify, introspect, and revoke.

Part of the AuthX monorepo. See the root README for service setup.

Install

Published to npm:

npm install -g @x12i/authx-token-cli

From the monorepo (after build):

npm run build
npx authx-token --help

Binary name: authx-token

Prerequisites

A running token service:

# From repo root
AUTHX_STORE=memory npm run dev:service
# → http://localhost:3100

Environment variables

| Variable | Default | Description | | --- | --- | --- | | AUTHX_API_URL | http://localhost:3100 | Service base URL | | AUTHX_API_KEY | — | Sent as x-authx-api-key when set | | AUTHX_OUTPUT | table | Default output: table or json |

Per-command override: --url <base> and --json.

Commands

Apps

# List registered apps
authx-token apps list

# Create app (appSecretKey shown once — save it!)
authx-token apps create \
  --app-id my-app \
  --title "My Application" \
  --description "Optional description"

# JSON output
authx-token apps create --app-id my-app --title "My App" --json

appId must match service validation: ^[a-z0-9][a-z0-9-_]*$

Tokens — issue

authx-token tokens issue \
  --app-id my-app \
  --identity-id user-42 \
  --identity-type user \
  --expires 3600

# Encrypted token (ax1e prefix)
authx-token tokens issue \
  --app-id my-app \
  --identity-id user-42 \
  --encrypt

--identity-type defaults to user. Allowed values: user, account, organization, service, agent.

Tokens — verify & introspect

authx-token tokens verify --token "$TOKEN"
authx-token tokens verify --token "$TOKEN" --app-id my-app

authx-token tokens introspect --token "$TOKEN"

Tokens — revoke

At least one selector is required (matches API):

# Single token
authx-token tokens revoke --token-id tok_abc123

# All tokens for an app
authx-token tokens revoke --app-id my-app

# All tokens for an identity
authx-token tokens revoke --identity-id user-42

Output formats

Table (default) — key/value lines for objects, one line per row for arrays:

authx-token apps list

JSON — use --json or AUTHX_OUTPUT=json:

authx-token apps list --json
export AUTHX_OUTPUT=json
authx-token tokens issue --app-id my-app --identity-id user-1

Secured API

When the service runs with AUTHX_API_KEY:

export AUTHX_API_KEY=your-secret
authx-token apps list

Or inline:

AUTHX_API_KEY=your-secret authx-token --url https://authx.example.com apps list

Typical workflow

# 1. Start service (separate terminal)
AUTHX_STORE=memory npm run dev:service

# 2. Register app
authx-token apps create --app-id demo --title "Demo" --json
# Save appSecretKey from output

# 3. Issue token
authx-token tokens issue --app-id demo --identity-id alice --json

# 4. Verify
export TOKEN="<paste token>"
authx-token tokens verify --token "$TOKEN" --json

# 5. Revoke
authx-token tokens revoke --token-id "<tokenId from issue response>"
authx-token tokens verify --token "$TOKEN" --json
# → valid: false, revoked: true

Development

npm run build -w @x12i/authx-token-cli
npm run typecheck -w @x12i/authx-token-cli

Source: src/cli.ts, src/config.ts, src/client.ts.

Related packages

| Package | Role | | --- | --- | | @x12i/authx-token-service | HTTP API this CLI calls | | @x12i/authx-token-types | Request/response types | | @x12i/authx-token-openapi | API contract |