npm package: @id-wispera/cli
Description: Command-line interface for ID Wispera credential governance
Author: Wispera AI Inc.
Latest version: 0.1.0

# @id-wispera/cli

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

## Installation

```bash
# 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.

```bash
# 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

```bash
# Create a new encrypted vault
idw init

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

### Create Passport

```bash
# 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

```bash
# 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

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

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

### Revoke Passport

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

### Share Passport

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

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

## License

MIT