VIUCraft CLI

Official command-line client for the VIUCraft image manipulation API.

Installation

npm install -g @viucraft/cli

Or with pnpm:

pnpm add -g @viucraft/cli

Requires Node.js 20 or later.

Quick Start

# Authenticate with your API key
viucraft auth login

# Upload an image
viucraft images upload photo.jpg

# Transform it
viucraft images transform --image <uuid> --ops "resize-800-600/sharp-1.2/q-85"

# List your images
viucraft images list

# Check usage
viucraft usage

Configuration

Profiles

The CLI supports multiple named profiles for switching between accounts or environments:

# Add profiles
viucraft auth login --profile production
viucraft auth login --profile staging

# Switch between them
viucraft auth switch production

# List all profiles
viucraft auth list

# Use a specific profile for one command
viucraft images list --profile staging

Environment Variables

| Variable | Description | |---|---| | VIUCRAFT_API_KEY | API key (overrides profile config) | | VIUCRAFT_PROFILE | Profile name to use | | VIUCRAFT_API_URL | API base URL override | | NO_COLOR | Disable colored output |

Config File

Configuration is stored at ~/.viucraft/config.yaml:

current_profile: default
profiles:
  default:
    api_key: "vc_live_..."
    api_url: "https://api.viucraft.com"
    environment: "live"
defaults:
  output_format: "table"
  color: true

Commands

Auth

| Command | Description | |---|---| | auth login | Authenticate with your API key | | auth status | Show current auth status and usage | | auth switch <profile> | Switch active profile | | auth list | List all profiles | | auth logout | Remove a profile |

Images

| Command | Description | |---|---| | images list | List uploaded images | | images upload <files...> | Upload one or more images | | images delete <uuid> | Delete an image | | images info <uuid> | Show image metadata | | images transform | Transform an image (returns URL) |

Batch Processing

| Command | Description | |---|---| | batch create --file <json> | Submit a batch job | | batch list | List batch jobs | | batch status <id> | Show job status and tasks | | batch stream <id> | Live-stream job progress (SSE) | | batch cancel <id> | Cancel a job | | batch retry <id> | Retry failed tasks | | batch download <id> | Download results as ZIP |

Presets

| Command | Description | |---|---| | presets list | List all presets | | presets get <name> | Show preset details | | presets create | Create a custom preset (Enterprise) | | presets delete <name> | Delete a custom preset (Enterprise) |

Cache

| Command | Description | |---|---| | cache purge | Purge cached images | | cache warm --image <uuid> | Pre-generate image variants |

Webhooks

| Command | Description | |---|---| | webhooks list | List webhook endpoints | | webhooks create | Create a webhook | | webhooks delete <id> | Delete a webhook | | webhooks test <id> | Send a test event |

Other

| Command | Description | |---|---| | usage | View account usage and limits | | config list | Show all configuration | | config get <key> | Get a config value | | config set <key> <value> | Set a config value | | completion bash\|zsh\|fish | Generate shell completions | | docs | Open documentation in browser | | version | Show CLI version |

Output Formats

All commands support --output json for machine-readable output:

# Pipe to jq
viucraft images list --output json | jq '.images[].uuid'

# Default table format
viucraft images list

Shell Completions

# Bash
viucraft completion bash >> ~/.bashrc

# Zsh
viucraft completion zsh >> ~/.zshrc

# Fish
viucraft completion fish > ~/.config/fish/completions/viucraft.fish

Global Flags

| Flag | Description | |---|---| | --api-key <key> | Override API key for this command | | --profile <name> | Use a specific profile | | --output <format> | Output format: table (default), json | | --no-color | Disable colored output | | --debug | Show HTTP request/response details | | --insecure | Allow HTTP connections (dev only) |

Development

Setup

git clone https://github.com/BStorm-IT/viucraft-cli.git
cd viucraft-cli
pnpm install
pnpm build

Try it locally

Run directly without installing globally:

pnpm start -- version
pnpm start -- --help
pnpm start -- images list --insecure

Or link globally so viucraft works anywhere in your terminal:

pnpm build && pnpm link --global

# Now use it like a real install
viucraft version
viucraft auth login
viucraft images list

# Unlink when done
pnpm unlink --global

Local dev server

To test against the VIUCraft API running locally (requires the viucraft server repo):

# Start the server (in the viucraft repo)
docker compose up -d

# Login with a test API key
viucraft auth login --api-key vc_test_YOUR_KEY --profile dev --api-url http://localhost:8080 --insecure

# Use commands with --insecure flag for http://
viucraft images list --insecure
viucraft images upload photo.jpg --insecure
viucraft usage --insecure

Quality gates

pnpm lint              # ESLint
pnpm typecheck         # TypeScript strict mode
pnpm test              # Vitest (49 tests)
pnpm format:check      # Prettier check
pnpm build             # tsup bundle

# Run all gates at once
pnpm lint && pnpm typecheck && pnpm test && pnpm build

# Fix formatting
pnpm format

# Dev mode (watch + rebuild on changes)
pnpm dev

CI

GitHub Actions runs on every push/PR to main:

• Lint job: ESLint + TypeScript + Prettier (ubuntu, Node 22)
• Test job: Vitest + build + smoke test (ubuntu + macOS, Node 20 + 22)
• Release: npm publish on v* tags

Security

• API keys stored locally at ~/.viucraft/config.yaml with 0600 permissions
• Keys are never printed in full — always masked as vc_live_...xxxx
• HTTPS enforced by default (use --insecure for local dev only)
• No telemetry or analytics

License

MIT