@viucraft/cli 0.1.1

package/README.md

@@ -0,0 +1,279 @@
+# VIUCraft CLI
+
+Official command-line client for the [VIUCraft](https://viucraft.com) image manipulation API.
+
+## Installation
+
+```bash
+npm install -g @viucraft/cli
+```
+
+Or with pnpm:
+
+```bash
+pnpm add -g @viucraft/cli
+```
+
+Requires Node.js 20 or later.
+
+## Quick Start
+
+```bash
+# 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:
+
+```bash
+# 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`:
+
+```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:
+
+```bash
+# Pipe to jq
+viucraft images list --output json | jq '.images[].uuid'
+
+# Default table format
+viucraft images list
+```
+
+## Shell Completions
+
+```bash
+# 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
+
+```bash
+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:
+
+```bash
+pnpm start -- version
+pnpm start -- --help
+pnpm start -- images list --insecure
+```
+
+Or link globally so `viucraft` works anywhere in your terminal:
+
+```bash
+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](https://github.com/BStorm-IT/viucraft) server repo):
+
+```bash
+# 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
+
+```bash
+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