@access-tokens/cli

Command-line interface for managing Personal Access Tokens (PATs).

Features

• Token Management: Issue, list, update, revoke, and restore tokens
• Configuration: Named endpoints for easy multi-environment management
• Bulk Operations: Sync tokens across environments from YAML config
• Local Generation: Generate tokens without server connection
• Flexible Output: JSON or human-readable output formats
• Secure Credentials: Config file permission validation

Installation

npm install -g @access-tokens/cli

Or use with npx (no installation):

npx @access-tokens/cli --help

Quick Start

Issue a Token

access-tokens issue \
  --url https://api.example.com \
  --admin-token <your-admin-token> \
  --owner [email protected] \
  --admin

List Tokens

access-tokens list \
  --url https://api.example.com \
  --admin-token <your-admin-token>

Using Named Endpoints

Create a config file at ~/.access-tokens-cli/config.yaml:

endpoints:
  prod:
    url: https://api.example.com
    adminToken: pat_prod_admin_token_here
  staging:
    url: https://staging.example.com
    adminToken: pat_staging_admin_token_here

Then use the endpoint name:

access-tokens list --endpoint prod
access-tokens issue --endpoint staging --owner [email protected]

Commands

generate

Generate a token locally without storing in database. Useful for pre-generating tokens.

access-tokens generate
access-tokens generate --token-prefix myapp_
access-tokens generate --token-id specific-id-123
access-tokens generate --json

Options:

• --token-prefix <prefix> - Token prefix (default: pat_)
• --token-id <id> - Use specific token ID
• --json - Output as JSON
• --verbose - Verbose output
• --quiet - Minimal output

Output:

Token: pat_9Xj2kLm5nPqRs7tUv.a8b9c0d1e2f3g4h5i6j7k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z3
Token ID: 9Xj2kLm5nPqRs7tUv
Secret PHC: $scrypt$n=16384,r=8,p=1$...

list

List all tokens.

access-tokens list --endpoint prod
access-tokens list --url https://api.example.com --admin-token <token>
access-tokens list --endpoint prod --include-revoked --include-expired
access-tokens list --endpoint prod --json

Options:

• --endpoint <name> - Named endpoint from config
• --url <url> - Direct endpoint URL
• --admin-token <token> - Admin token (required with --url)
• --auth-path <path> - Auth path (default: /auth)
• --admin-path <path> - Admin path (default: /admin)
• --config-dir <path> - Config directory (default: ~/.access-tokens-cli)
• --include-revoked - Include revoked tokens
• --include-expired - Include expired tokens
• --include-secret-phc - Include secret PHC hashes
• --json - Output as JSON
• --verbose - Verbose output
• --quiet - Minimal output

issue

Issue a new token.

access-tokens issue \
  --endpoint prod \
  --owner [email protected] \
  --admin

access-tokens issue \
  --url https://api.example.com \
  --admin-token <token> \
  --owner [email protected] \
  --expires-at 2025-12-31

Options:

• --endpoint <name> - Named endpoint from config
• --url <url> - Direct endpoint URL
• --admin-token <token> - Admin token (required with --url)
• --auth-path <path> - Auth path (default: /auth)
• --admin-path <path> - Admin path (default: /admin)
• --config-dir <path> - Config directory (default: ~/.access-tokens-cli)
• --owner <email> - Token owner (required)
• --admin - Make token an admin token
• --expires-at <date> - Expiration date (ISO 8601 or Unix timestamp)
• --json - Output as JSON
• --verbose - Verbose output
• --quiet - Minimal output

Date Formats:

• ISO 8601: 2025-12-31, 2025-12-31T23:59:59Z
• Unix timestamp: 1735689599

register

Register a pre-generated token (from generate command).

access-tokens register \
  --endpoint prod \
  --token-id 9Xj2kLm5nPqRs7tUv \
  --secret-phc '$scrypt$n=16384,r=8,p=1$...' \
  --owner [email protected]

Options:

• --endpoint <name> - Named endpoint from config
• --url <url> - Direct endpoint URL
• --admin-token <token> - Admin token (required with --url)
• --auth-path <path> - Auth path (default: /auth)
• --admin-path <path> - Admin path (default: /admin)
• --config-dir <path> - Config directory (default: ~/.access-tokens-cli)
• --token-id <id> - Pre-generated token ID (required)
• --secret-phc <phc> - Secret PHC hash (required)
• --owner <email> - Token owner (required)
• --admin - Make token an admin token
• --expires-at <date> - Expiration date
• --json - Output as JSON
• --verbose - Verbose output
• --quiet - Minimal output

update

Update an existing token's properties.

access-tokens update \
  --endpoint prod \
  --token-id 9Xj2kLm5nPqRs7tUv \
  --owner [email protected]

access-tokens update \
  --endpoint prod \
  --token-id 9Xj2kLm5nPqRs7tUv \
  --admin true

access-tokens update \
  --endpoint prod \
  --token-id 9Xj2kLm5nPqRs7tUv \
  --expires-at null

Options:

• --endpoint <name> - Named endpoint from config
• --url <url> - Direct endpoint URL
• --admin-token <token> - Admin token (required with --url)
• --auth-path <path> - Auth path (default: /auth)
• --admin-path <path> - Admin path (default: /admin)
• --config-dir <path> - Config directory (default: ~/.access-tokens-cli)
• --token-id <id> - Token ID to update (required)
• --owner <email> - New owner
• --admin <boolean> - New admin status (true/false)
• --secret-phc <phc> - New secret PHC hash
• --expires-at <date> - New expiration or "null" to remove
• --verbose - Verbose output
• --quiet - Minimal output

revoke

Revoke a token.

access-tokens revoke --endpoint prod --token-id 9Xj2kLm5nPqRs7tUv

# Revoke with cleanup in 30 days
access-tokens revoke \
  --endpoint prod \
  --token-id 9Xj2kLm5nPqRs7tUv \
  --expires-at 2025-12-31

Options:

• --endpoint <name> - Named endpoint from config
• --url <url> - Direct endpoint URL
• --admin-token <token> - Admin token (required with --url)
• --auth-path <path> - Auth path (default: /auth)
• --admin-path <path> - Admin path (default: /admin)
• --config-dir <path> - Config directory (default: ~/.access-tokens-cli)
• --token-id <id> - Token ID to revoke (required)
• --expires-at <date> - Expiration for cleanup (optional)
• --verbose - Verbose output
• --quiet - Minimal output

restore

Restore a previously revoked token.

access-tokens restore --endpoint prod --token-id 9Xj2kLm5nPqRs7tUv

Options:

• --endpoint <name> - Named endpoint from config
• --url <url> - Direct endpoint URL
• --admin-token <token> - Admin token (required with --url)
• --auth-path <path> - Auth path (default: /auth)
• --admin-path <path> - Admin path (default: /admin)
• --config-dir <path> - Config directory (default: ~/.access-tokens-cli)
• --token-id <id> - Token ID to restore (required)
• --verbose - Verbose output
• --quiet - Minimal output

sync

Sync tokens from YAML config to endpoints. Ensures tokens exist with correct properties.

Sync Config (sync.yaml):

tokens:
  - tokenId: service-a-prod
    owner: [email protected]
    isAdmin: false
    secretPhc: $scrypt$n=16384,r=8,p=1$...
    expiresAt: 1735689599

  - tokenId: admin-bot
    owner: [email protected]
    isAdmin: true
    secretPhc: $scrypt$n=16384,r=8,p=1$...

Usage:

# Sync to configured endpoints
access-tokens sync --config sync.yaml

# Sync to specific endpoint
access-tokens sync --config sync.yaml --endpoint prod

# Sync to direct URL
access-tokens sync --config sync.yaml --url https://api.example.com --admin-token <token>

# Dry run (preview changes)
access-tokens sync --config sync.yaml --dry-run

Options:

• --config <path> - Path to sync config YAML (required)
• --endpoint <name> - Target endpoint(s), comma-separated
• --url <url> - Direct endpoint URL (overrides config)
• --admin-token <token> - Admin token (required with --url)
• --auth-path <path> - Auth path (default: /auth)
• --admin-path <path> - Admin path (default: /admin)
• --config-dir <path> - Config directory (default: ~/.access-tokens-cli)
• --dry-run - Show changes without applying
• --verbose - Verbose output
• --quiet - Minimal output

Configuration

Config File Location

Default: ~/.access-tokens-cli/config.yaml

Override: --config-dir <path>

Config File Format

endpoints:
  prod:
    url: https://api.example.com
    adminToken: pat_prod_admin_token
    authPath: /auth # optional, default: /auth
    adminPath: /admin # optional, default: /admin

  staging:
    url: https://staging.example.com
    adminToken: pat_staging_admin_token

Security

The CLI validates config file permissions and warns if the file is world-readable (mode 0644 or more permissive).

Secure your config:

chmod 600 ~/.access-tokens-cli/config.yaml

Output Formats

Human-Readable (Default)

Token issued successfully!

TOKEN (save this securely, it won't be shown again):
pat_9Xj2kLm5nPqRs7tUv.a8b9c0d1e2f3g4h5i6j7k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z3

Token ID: 9Xj2kLm5nPqRs7tUv
Owner: [email protected]
Admin: true

JSON (--json)

{
  "token": "pat_9Xj2kLm5nPqRs7tUv.a8b9c0d1e2f3g4h5i6j7k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z3",
  "record": {
    "tokenId": "9Xj2kLm5nPqRs7tUv",
    "owner": "[email protected]",
    "isAdmin": true,
    "isRevoked": false,
    "createdAt": 1704067200,
    "updatedAt": 1704067200
  }
}

Exit Codes

• 0 - Success
• 1 - Error (invalid arguments, API error, etc.)

Requirements

• Node.js 20+
• @access-tokens/express server (except generate)

Related Packages

• @access-tokens/core - Core token management library
• @access-tokens/express - Express routes and middleware
• @access-tokens/client - HTTP client for PAT API

License

ISC © 2025 Loan Crate, Inc.

Links

• GitHub Repository
• npm Package
• Documentation