@visionfi/desktop-cli/README.md

Command-line interface for VisionFI Desktop SDK

# VisionFI Desktop CLI

Command-line interface for VisionFI Desktop SDK with Azure AD authentication and automatic endpoint discovery.

## Installation

```bash
npm install -g @visionfi/desktop-cli
```

Or run without installing:

```bash
npx @visionfi/desktop-cli
```

## Quick Start

1. **Login** (automatically discovers your API endpoint):
   ```bash
   visionfi-desktop auth login
   ```

2. **List packages**:
   ```bash
   visionfi-desktop package list
   ```

3. **Get help**:
   ```bash
   visionfi-desktop --help
   ```

## Authentication

The CLI uses **Azure AD authentication** with automatic endpoint discovery via the Beacon service. No manual configuration required!

### First Time Setup

```bash
# Login with Azure AD (opens browser)
visionfi-desktop auth login
```

This will:
1. Open your browser for Azure AD authentication
2. Automatically discover your API endpoint via Beacon service
3. Save your configuration for future use

### Authentication Commands

```bash
visionfi-desktop auth login        # Login with Azure AD + auto-discover endpoint
visionfi-desktop auth logout       # Logout and clear tokens
visionfi-desktop auth verify       # Check authentication status
visionfi-desktop auth token        # Get token (debugging)
```

## Package Management

### List Packages

```bash
# List all packages
visionfi-desktop package list

# List with JSON output
visionfi-desktop package list --format json

# Filter by status
visionfi-desktop package list --status ready
```

### Create Package

```bash
visionfi-desktop package create \
  --product-type sync1-loan-application-test \
  --description "My loan application"
```

### Get Package Details

```bash
visionfi-desktop package get <package-id>
```

### Package Audit History

```bash
visionfi-desktop package audit <package-id>
```

## Document Management

### Add Documents

```bash
visionfi-desktop package document add <package-id> \
  --file document1.pdf \
  --file document2.pdf
```

### Delete Document

```bash
visionfi-desktop package document delete <package-id> <document-id>
```

## Processing Operations

### Execute Processing

```bash
visionfi-desktop package processing execute <package-id> \
  --workflow vehicle-info-extraction
```

### Get Processing History

```bash
visionfi-desktop package processing history <package-id>
```

### Get Processing Result

```bash
visionfi-desktop package processing result <package-id> <process-id>
```

### View Processing Output

```bash
visionfi-desktop package processing view <package-id> <process-id>
```

### Poll Processing Status

```bash
visionfi-desktop package processing poll <package-id> <process-id>
```

## External References

### Add References

```bash
visionfi-desktop package ref add <package-id> \
  --refs ref-id-1 ref-id-2
```

### Remove References

```bash
visionfi-desktop package ref remove <package-id> \
  --refs ref-id-1 ref-id-2
```

## Administrative Commands

### Get Product Types

```bash
visionfi-desktop admin products
```

### Get Client Information

```bash
visionfi-desktop admin client
```

## Configuration

### View Config Location

```bash
visionfi-desktop config
```

Configuration is stored at: `~/.visionfi/desktop/config.json`

### Environment Variables

You can override defaults with environment variables:

```bash
# Override Azure AD client ID (optional)
export AZURE_CLIENT_ID=your-client-id

# Override Azure AD tenant ID (optional)
export AZURE_TENANT_ID=your-tenant-id

# Override Beacon service URL (optional)
export VISIONFI_BEACON_URL=https://beacon.visionfi.ai

# Override API endpoint (bypasses Beacon discovery)
export VISIONFI_CLOUD_RUN_ENDPOINT=https://your-endpoint.run.app
```

## Command Aliases

For convenience, some commands have shorter aliases:

- `package` → `pkg`
- `document` → `doc`
- `processing` → `proc`

Examples:
```bash
visionfi-desktop pkg list
visionfi-desktop pkg doc add <package-id> --file document.pdf
visionfi-desktop pkg proc execute <package-id> --workflow extraction
```

## Common Workflows

### Create and Process a Loan Application

```bash
# 1. Create package
visionfi-desktop pkg create \
  --product-type sync1-loan-application-test \
  --description "Auto loan application"

# 2. Add documents
visionfi-desktop pkg doc add <package-id> \
  --file application.pdf \
  --file paystub.pdf

# 3. Execute processing
visionfi-desktop pkg proc execute <package-id> \
  --workflow vehicle-info-extraction

# 4. Poll for results
visionfi-desktop pkg proc poll <package-id> <process-id>

# 5. View results
visionfi-desktop pkg proc result <package-id> <process-id>
```

## Output Formats

Most commands support different output formats:

```bash
# Table format (default)
visionfi-desktop package list

# JSON format
visionfi-desktop package list --format json

# YAML format
visionfi-desktop package list --format yaml
```

## Security

The CLI follows security best practices for credential storage:

- **Token Cache**: Stored at `~/.visionfi/desktop/msal-cache.json` with `0600` permissions (user-only read/write)
- **Azure AD Tokens**: Automatically refreshed, no passwords stored
- **Device Code Flow**: Secure authentication without local HTTP server

## Troubleshooting

### Authentication Issues

```bash
# Check authentication status
visionfi-desktop auth verify

# Re-authenticate
visionfi-desktop auth logout
visionfi-desktop auth login
```

### Token Expired

If you see "Session expired" errors:

```bash
visionfi-desktop auth login
```

### Clear All Data

```bash
# Logout and clear cache
visionfi-desktop auth logout

# Manually remove config
rm -rf ~/.visionfi/desktop/
```

## License

Copyright (c) 2024-2025 VisionFI. All Rights Reserved.