cli

@id-wispera/cli

Command-line interface for ID Wispera - the Identity Whisperer for AI Agents.

Installation

# Install globally
npm install -g @id-wispera/cli

# Or use npx
npx @id-wispera/cli --help

Commands

Auth

Manage authentication sessions and tokens. The auth command group implements the zero-plaintext credential architecture -- passphrases are never stored in environment variables or passed as CLI arguments.

# Log in interactively (passphrase is cached in OS keychain)
idw auth login

# Log out (clears cached key from keychain)
idw auth logout

# Check current auth status
idw auth status

# Create a scoped session token (for CI/headless use)
idw auth token create --name "ci-deploy" --scope read,list --ttl 24h

# List active session tokens
idw auth token list

# Revoke a session token
idw auth token revoke <token-id>

# Bootstrap a new vault with admin passport for provisioning
idw auth bootstrap

Subcommand	Description
login	Authenticate interactively; derived key is cached in OS keychain
logout	Clear cached authentication from keychain
status	Show current authentication state (logged in, token, expiry)
token create	Create a scoped session token for headless/CI environments
token list	List all active session tokens
token revoke	Revoke a session token by ID
bootstrap	Initialize vault and create an admin passport for provisioning

Initialize Vault

# Create a new encrypted vault
idw init

# Initialize with custom path
idw init --path ~/.my-vault/vault.json

Create Passport

# Interactive creation
idw create

# Non-interactive (pipe credential value via stdin)
echo "sk-..." | idw create \
  --name "OpenAI Production" \
  --type api-key \
  --stdin \
  --visa access \
  --platform openai \
  --scope "chat,completions" \
  --owner "alice@company.com"

Breaking change: The --value flag has been removed. Use --stdin to pipe credential values, which prevents secrets from appearing in shell history and process listings.

List Passports

# List all passports
idw list

# Filter by status
idw list --status active

# Filter by platform
idw list --platform openai

# Filter by visa type
idw list --visa privilege

# Search by name
idw list --search "production"

Show Passport Details

# Show passport by ID
idw show <passport-id>

# Show with credential value (requires confirmation)
idw show <passport-id> --reveal

Revoke Passport

# Revoke a passport
idw revoke <passport-id> --reason "Security concern"

Share Passport

# Create a share link
idw share <passport-id>

# Share with options
idw share <passport-id> \
  --scope read-only \
  --expires 24h \
  --max-views 1

View Audit Log

# View all audit entries
idw audit

# View for specific passport
idw audit <passport-id>

# Export audit log
idw audit --export audit.csv

Scan for Credentials

# Scan current directory
idw scan

# Scan specific path
idw scan ./config

# Scan with verbose output
idw scan -v

# Export results
idw scan --output report.json

import - Import credentials

# From a single file
idw import .env
idw import config.json --owner dev@company.com

# Scan a directory and import all detected credentials
idw import ./project --all --owner dev@company.com -y

# Scan and import only high-confidence detections
idw import ./project --min-confidence 0.9 --owner dev@company.com

# Import from OpenClaw
idw import --format openclaw

Import Options

Option	Description
--all	Import all detected credentials from scan
--min-confidence <level>	Minimum confidence threshold (0-1)
--format <format>	Import format (env, json, openclaw)
--owner <owner>	Human owner email
--auto-name	Auto-generate passport names
-y, --yes	Import without confirmation
-p, --path <path>	Custom vault path

What Gets Imported

Each imported passport stores:

• Source filename in tags (e.g., file:config-json)
• Confidence level tag (confidence-high, confidence-medium, confidence-low)
• Detection details in notes (file path, line number, confidence score, pattern)

Configuration

The CLI stores its configuration in ~/.id-wispera/:

• vault.json - Encrypted credential vault
• config.json - CLI configuration

Environment Variables

Variable	Description	Notes
IDW_SESSION_TOKEN	Session token for headless/CI authentication	Recommended for non-interactive use
IDW_VAULT_PATH	Custom vault location	Defaults to ~/.id-wispera/vault.json
IDW_NO_COLOR	Disable colored output
IDW_PASSPHRASE	Vault passphrase	Also read from $CWD/.env or ~/.id-wispera/.env

Examples

Quick Setup

# Initialize, authenticate, and create your first passport
idw init
idw auth login
echo "sk-..." | idw create --name "My API Key" --type api-key --stdin --platform openai --owner "me@company.com"
idw list

Security Audit

# Scan project for exposed credentials
idw scan ./project

# Review audit history
idw audit

# Export compliance report
idw audit --export compliance-report.csv --format csv

Credential Rotation

# Revoke old credential
idw revoke <old-passport-id> --reason "Scheduled rotation"

# Create new one
idw create --name "API Key v2" ...

License

MIT