CLI Configuration

Complete guide to configuring the licenz command-line interface, including configuration files, environment variables, and credential storage.

Configuration Overview

The Licenz CLI can be configured through multiple methods, listed in order of precedence:

Command-line arguments (highest priority)
Environment variables
Configuration files
Default values (lowest priority)

Configuration Files

Location

The CLI stores configuration and credentials in platform-specific directories:

Platform	Config Directory
Linux	`~/.config/licenz/`
macOS	`~/Library/Application Support/io.licenz.licenz/`
Windows	`C:\Users\<USER>\AppData\Roaming\licenz\licenz\`

Credentials File

After running licenz server login, credentials are stored in a credentials file:

# ~/.config/licenz/credentials (Linux)
server_url = "https://api.licenz.io"
keyring_stored = true  # API key stored in OS keyring

When using file-based storage (with --insecure-storage):

# Warning: API key stored in plaintext
api_key = "lk_live_..."
server_url = "https://api.licenz.io"

Credential Storage

The CLI supports two methods for storing API credentials:

OS Keyring (Recommended)

By default, the CLI stores API keys securely in the operating system's native keyring:

macOS: Keychain
Linux: Secret Service (GNOME Keyring, KWallet)
Windows: Credential Manager

# Login with secure keyring storage (default)
licenz server login

File-Based Storage

If keyring is unavailable, use file-based storage with the --insecure-storage flag:

# Warning: stores API key in plaintext file
licenz server login --insecure-storage

The credentials file is created with restricted permissions (0600 on Unix).

Environment Variables

Environment variables provide a convenient way to configure the CLI, especially in CI/CD pipelines.

Variable	Description	Example
`LICENZ_API_KEY`	API key for server authentication	`lk_live_abc123...`
`LICENZ_ORG_ID`	Default organization ID	`org_xyz789`
`LICENZ_API_URL`	API endpoint URL (for self-hosted)	`https://licenz.example.com`
`LICENZ_CONFIG_PATH`	Path to configuration directory	`/etc/licenz`

Using Environment Variables

# Set API key for the session
export LICENZ_API_KEY="lk_live_abc123..."

# Use custom server URL (self-hosted)
export LICENZ_API_URL="https://licenz.internal.company.com"

# Run commands without storing credentials
licenz server products

CI/CD Configuration

# GitHub Actions example
jobs:
  deploy-license:
    runs-on: ubuntu-latest
    steps:
      - name: Create license
        env:
          LICENZ_API_KEY: ${{ secrets.LICENZ_API_KEY }}
        run: |
          licenz server license create \
            --product prod_abc123 \
            --customer customer@example.com \
            --days 365

Server Login

Authentication with the Licenz SaaS server requires logging in with an API key.

`licenz server login`

Authenticate with the Licenz server.

licenz server login \
  [--server <URL>] \
  [--api-key <KEY>] \
  [--insecure-storage]

Option	Description	Default
`--server <URL>`	Server URL (must be HTTPS, except localhost)	`https://api.licenz.io`
`--api-key <KEY>`	API key (prompts interactively if not provided)	-
`--insecure-storage`	Store credentials in plaintext file instead of OS keyring	`false`

Examples

# Interactive login (prompts for API key)
licenz server login

# Non-interactive login
licenz server login --api-key lk_live_abc123...

# Self-hosted server
licenz server login --server https://licenz.internal.company.com

# Headless/CI environment without keyring
licenz server login --api-key $API_KEY --insecure-storage

`licenz server logout`

Remove stored credentials from keyring and config files.

licenz server logout

`licenz server status`

Check current authentication status and display organization information.

licenz server status

Default Paths

Many commands use default paths that can be overridden with options:

File Type	Default Path	Override Option
Private key	`keys/private.pem`	`--key`
Public key	`keys/public.pem`	`--key`
License file	`license.lic`	`--license`, `--output`
Activation request	`activation.req`	`--output`
Key directory	`keys/`	`--dir`

Verbose Mode

Enable detailed logging with the global --verbose flag:

# Enable debug output
licenz --verbose license verify license.lic

# Alias
licenz -v sneakernet request --product prod_abc123

Output Formats

Most commands support JSON output for scripting and automation:

# Human-readable output (default)
licenz license info

# JSON output for scripting
licenz license info --json | jq '.features'

# Use in scripts
LICENSE_ID=$(licenz server license create --json | jq -r '.id')

Security Best Practices

Always use OS keyring storage when available
Never commit API keys to version control
Use environment variables in CI/CD rather than config files
Rotate API keys regularly
Use separate API keys for development and production
Restrict file permissions on credential files (chmod 600)

Troubleshooting

Keyring Not Available

If you see "Failed to store in keyring" errors:

# Linux: Ensure secret service is running
sudo systemctl start gnome-keyring-daemon

# Or use file-based storage as fallback
licenz server login --insecure-storage

Permission Denied

If credential files have incorrect permissions:

# Fix permissions on Linux/macOS
chmod 600 ~/.config/licenz/credentials

Self-Hosted Server Connection

For self-hosted installations with custom certificates:

# HTTPS is required (except for localhost during development)
licenz server login --server https://licenz.internal.company.com

# For development only (localhost allows HTTP)
licenz server login --server http://localhost:8080