Skip to content

authlete/authlete-cli

BranchesTags

Repository files navigation

authlete

Command-line interface for the Authlete API.

Built by Speakeasy License: MIT

Summary

Authlete API: Welcome to the Authlete API documentation. Authlete is an API-first service where every aspect of the platform is configurable via API. This documentation will help you authenticate and integrate with Authlete to build powerful OAuth 2.0 and OpenID Connect servers.

At a high level, the Authlete API is grouped into two categories:

  • Management APIs: Enable you to manage services and clients.
  • Runtime APIs: Allow you to build your own Authorization Servers or Verifiable Credential (VC) issuers.

🌐 API Servers

Authlete is a global service with clusters available in multiple regions across the world:

  • 🇺🇸 US: https://us.authlete.com
  • 🇯🇵 Japan: https://jp.authlete.com
  • 🇪🇺 Europe: https://eu.authlete.com
  • 🇧🇷 Brazil: https://br.authlete.com

Our customers can host their data in the region that best meets their requirements.

🔑 Authentication

All API endpoints are secured using Bearer token authentication. You must include an access token in every request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Getting Your Access Token

Authlete supports two types of access tokens:

Service Access Token - Scoped to a single service (authorization server instance)

  1. Log in to Authlete Console
  2. Navigate to your service → Settings → Access Tokens
  3. Click Create Token and select permissions (e.g., service.read, client.write)
  4. Copy the generated token

Organization Token - Scoped to your entire organization

  1. Log in to Authlete Console
  2. Navigate to Organization Settings → Access Tokens
  3. Click Create Token and select org-level permissions
  4. Copy the generated token

⚠️ Important Note: Tokens inherit the permissions of the account that creates them. Service tokens can only access their specific service, while organization tokens can access all services within your org.

Token Security Best Practices

  • Never commit tokens to version control - Store in environment variables or secure secret managers
  • Rotate regularly - Generate new tokens periodically and revoke old ones
  • Scope appropriately - Request only the permissions your application needs
  • Revoke unused tokens - Delete tokens you're no longer using from the console

Quick Test

Verify your token works with a simple API call:

curl -X GET https://us.authlete.com/api/service/get/list \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

🎓 Tutorials

If you're new to Authlete or want to see sample implementations, these resources will help you get started:

🛠 Contact Us

If you have any questions or need assistance, our team is here to help:

Table of Contents

CLI Installation

Quick Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/authlete/authlete-cli/main/scripts/install.sh | bash

Quick Install (Windows PowerShell)

iwr -useb https://raw.githubusercontent.com/authlete/authlete-cli/main/scripts/install.ps1 | iex

Homebrew (macOS/Linux)

brew install authlete/tap/authlete

Go Install

Alternatively, install directly via Go:

go install github.com/authlete/authlete-cli/cmd/authlete@latest

Manual Download

Download pre-built binaries for your platform from the releases page.

Shell Completion

Shell completions are available for Bash, Zsh, Fish, and PowerShell.

Bash

# Add to ~/.bashrc:
source <(authlete completion bash)

# Or install permanently:
authlete completion bash > /etc/bash_completion.d/authlete

Zsh

# Add to ~/.zshrc:
source <(authlete completion zsh)

# Or install permanently:
authlete completion zsh > "${fpath[1]}/_authlete"

Fish

authlete completion fish | source

# Or install permanently:
authlete completion fish > ~/.config/fish/completions/authlete.fish

PowerShell

authlete completion powershell | Out-String | Invoke-Expression

CLI Example Usage

Example

authlete service get --bearer 'Bearer test_token' --service-id '<id>'

Authentication

Authentication credentials can be configured in four ways (in order of priority):

1. Command-line flags

Pass credentials directly as flags to any command:

authlete --bearer <value> <command> [arguments]

2. Environment variables

Set credentials via environment variables:

Variable Description
AUTHLETE_BEARER Authenticate every request with a Service Access Token or Organization Token.
Set the token value in the Authorization: Bearer <token> header.

Service Access Token: Scoped to a single service. Use when automating service-level configuration or runtime flows.

Organization Token: Scoped to the organization; inherits permissions across services. Use for org-wide automation or when managing multiple services programmatically.

Both token types are issued by the Authlete console or provisioning APIs. |

3. OS Keychain (recommended for workstations)

Credentials are stored securely in your operating system's keychain when you run:

authlete configure

Secret credentials (tokens, API keys, passwords) are automatically stored in:

  • macOS: Keychain
  • Linux: GNOME Keyring / KWallet (via D-Bus Secret Service)
  • Windows: Windows Credential Locker

If no keychain is available (e.g., in CI environments), credentials fall back to the config file.

4. Configuration file

Run the interactive configure command to store non-secret settings:

authlete configure

Configuration is stored in ~/.config/authlete/config.yaml.

Available Commands

Available commands

service

client

client-management

authorization

  • process-request - Process Authorization Request
  • fail - Fail Authorization Request
  • issue - Issue Authorization Response

authorization-management

pushed-authorization

  • create - Process Pushed Authorization Request

token

  • process - Process Token Request
  • fail - Fail Token Request
  • issue - Issue Token Response

token-management

introspection

revocation

  • process - Process Revocation Request

userinfo

  • process - Process UserInfo Request
  • issue - Issue UserInfo Response

grant-management

JWK-set-endpoint

dynamic-client-registration

ciba

  • process-authentication - Process Backchannel Authentication Request
  • issue - Issue Backchannel Authentication Response
  • fail - Fail Backchannel Authentication Request
  • complete - Complete Backchannel Authentication

device-flow

jose-object

federation

hardware-security-keys

  • create - Create Security Key
  • delete - Delete Security Key
  • get - Get Security Key
  • list - List Security Keys

verifiable-credentials

lifecycle

native-sso

  • process - Native SSO Processing
  • logout - Native SSO Logout Processing

Request Body Input

Operations that accept a request body support three input methods, with a clear priority chain:

Individual flags (highest priority)

authlete <command> --name "Jane" --age 30

--body flag

Provide the entire request body as a JSON string:

authlete <command> --body '{"name": "John", "age": 30}'

Individual flags override --body values:

# Result: {name: "Jane", age: 30}
authlete <command> --body '{"name": "John", "age": 30}' --name "Jane"

Stdin piping (lowest priority)

Pipe JSON into any command that accepts a request body:

echo '{"name": "John", "age": 30}' | authlete <command>

Individual flags override stdin values:

# Result: {name: "Jane", age: 30}
echo '{"name": "John", "age": 30}' | authlete <command> --name "Jane"

This is useful for chaining commands, reading from files, or scripting:

# Read body from a file
authlete <command> < request.json

# Pipe from another command
curl -s https://example.com/data.json | authlete <command>

Priority

When multiple input methods are used, the priority is:

Priority Source Description
1 (highest) Individual flags --name "Jane" always wins
2 --body flag Whole-body JSON via flag
3 (lowest) Stdin Piped JSON input

Server Selection

Select Server by Index

Use --server <index> to select a server by its zero-based index (default: 0):

# Server Description
0 https://us.authlete.com 🇺🇸 US Cluster
1 https://jp.authlete.com 🇯🇵 Japan Cluster
2 https://eu.authlete.com 🇪🇺 Europe Cluster
3 https://br.authlete.com 🇧🇷 Brazil Cluster 
authlete --server <index> <command> [arguments]

Override Server URL

Use --server-url to override the server URL entirely, bypassing any named or indexed server selection:

authlete --server-url https://custom-api.example.com <command> [arguments]

Precedence: --server-url > --server > default

Output Formats

Every command supports a --output-format flag that controls how the response is rendered to stdout.

Available formats

Format Flag Description
Pretty --output-format pretty (default) Aligned key-value pairs with color, nested indentation. Human-readable at a glance.
JSON --output-format json JSON output. Passthrough when the response is already JSON (preserves original field order and numeric precision). Falls back to typed marshaling otherwise.
YAML --output-format yaml YAML output via standard marshaling.
Table --output-format table Tabular output for array responses.
TOON --output-format toon Token-Oriented Object Notation — a compact, line-oriented format that typically uses 30–60% fewer tokens than JSON. Well-suited for piping responses into LLM prompts. 
# Default pretty output
authlete <command>

# Machine-readable JSON
authlete <command> --output-format json

# TOON for LLM-friendly compact output
authlete <command> --output-format toon

# Pipe JSON to jq without using --output-format
authlete <command> --output-format json | jq '.fieldName'

jq filtering

Use --jq to filter or transform the response inline using a jq expression. This always outputs JSON and overrides --output-format:

# Extract a single field
authlete <command> --jq '.name'

# Filter an array
authlete <command> --jq '.items[] | select(.active == true)'

Color control

Use --color to control terminal colors:

Value Behavior
auto (default) Color when stdout is a TTY, plain text otherwise
always Always colorize
never Never colorize

The NO_COLOR and FORCE_COLOR environment variables are also respected.

Streaming and pagination

When using --all (pagination) or streaming operations, output is written incrementally as items arrive:

Format Streaming behavior
json One compact JSON object per line (NDJSON)
yaml YAML documents separated by ---
toon One TOON-encoded object per block, separated by blank lines
pretty (default) Pretty-printed items separated by blank lines

Error Handling

The CLI uses standard exit codes to indicate success or failure:

Exit Code Meaning
0 Success
1 Error (API error, invalid input, etc.)

On success, the response data is printed to stdout as JSON. On failure, error details are printed to stderr.

# Capture output and handle errors
authlete ... > output.json 2> error.log
if [ $? -ne 0 ]; then
  echo "Error occurred, see error.log"
fi

Diagnostics

The CLI includes two diagnostic flags available on all commands:

Dry Run

Preview what would be sent without making any network calls:

authlete <command> --dry-run

Output goes to stderr and includes:

  • HTTP method and URL
  • Request headers (sensitive values redacted)
  • Request body preview (sensitive fields redacted)

The command exits successfully without contacting the API. This is useful for verifying request construction before executing.

Debug

Log request and response diagnostics while running normally:

authlete <command> --debug

Debug output goes to stderr and includes:

  • Request method, URL, headers, and body preview
  • Response status, headers, and body preview
  • Transport errors (if any)

The command still executes normally and produces its regular output on stdout.

Flag Precedence

If both --dry-run and --debug are set, --dry-run takes precedence and no network calls are made.

Security

Sensitive information is automatically redacted in diagnostic output:

  • Headers: Authorization, Cookie, Set-Cookie, X-API-Key, and other security headers show [REDACTED]
  • Body: JSON fields named password, secret, token, api_key, client_secret, etc. show [REDACTED]

Diagnostic output should still be treated as potentially sensitive operational data.

Development

Maturity

This CLI is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this CLI, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

CLI Created by Speakeasy

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 3

v0.0.9 Latest
Apr 17, 2026
+ 2 releases

Packages

 
 
 

Contributors

Languages