@vtriv/cli 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # vtriv CLI
 
-Command-line interface for vtriv backend services.
+Command-line interface for vtriv backend services. Uses account-based authentication to manage projects.
 
 ## Installation
 
@@ -16,53 +16,260 @@ bun link
 vtriv --help
 ```
 
+## Authentication Model
+
+The CLI uses a two-tier authentication system:
+
+1. **Account Key** (`vtriv_ak_...`) - Used to create and manage projects
+2. **API Keys** (`vtriv_sk_...`) - Per-project, used to mint JWTs for service calls
+
+Configuration is stored in `~/.config/vtriv/config.json` with `0600` permissions.
+
+### How It Works
+
+1. Run `vtriv config` to set up your account key
+2. Run `vtriv init <name>` to create a project and API key
+3. CLI uses the API key to mint short-lived JWTs
+4. JWTs are cached for 55 minutes (tokens valid for 60)
+
+Project names are automatically prefixed with your account slug (e.g., `a1b2c3d4-my-app`), but you work with short names in the CLI.
+
 ## Setup
 
+### Configure Account
+
 ```bash
-# Initialize configuration
-vtriv init
+vtriv config
 ```
 
-This creates `~/.vtrivrc` with your API gateway URL and bootstrap key.
+You'll be prompted for:
+- Base URL (default: `http://localhost:3000`)
+- Account key (`vtriv_ak_...`)
+
+The CLI verifies the account key and fetches your account slug.
 
-## Quick Start
+### Create a Project
 
 ```bash
-# List projects
-vtriv auth project:list
+vtriv init my-app
+```
 
-# Create a project
-vtriv auth project:create my-app
+This:
+1. Creates project `{slug}-my-app` on the server
+2. Creates an API key for the project
+3. Saves the profile locally
 
-# Create a user
-vtriv auth user:create my-app admin@example.com secretpass
+### Multiple Projects
 
-# List documents
-vtriv db ls my-app posts
+```bash
+# Create another project
+vtriv init staging --default
 
-# Create a document
-echo '{"title":"Hello"}' | vtriv db put my-app posts
+# Use a specific profile
+vtriv --profile my-app db ls posts
+```
+
+### View Status
 
-# Search
-vtriv search query my-app posts "hello world"
+```bash
+vtriv status
+```
+
+Shows your account, configured profiles, and which is default.
+
+### Manage Projects
+
+```bash
+# List all projects
+vtriv project ls
+
+# Delete a project
+vtriv project rm my-app
 ```
 
 ## Commands
 
-- `vtriv init` - Setup configuration
-- `vtriv auth` - Auth service (projects, users, tokens, API keys)
-- `vtriv db` - Database service (ls, get, put, rm, schema)
-- `vtriv blob` - Blob storage (put, get, rm)
-- `vtriv cron` - Cron jobs (ls, runs, trigger, script:cat)
-- `vtriv ai` - AI service (stats, chat)
-- `vtriv search` - Search service (config, query)
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output raw JSON (for scripts/agents) |
+| `--profile <name>` | Use a specific profile |
+| `--debug` | Show HTTP curl equivalents |
+
+### Token Commands
+
+```bash
+# Mint and display a JWT
+vtriv token
+
+# Mint with specific template
+vtriv token --template ai-enabled
+```
+
+### Template Commands
+
+Manage token templates for your project.
+
+```bash
+# List all templates
+vtriv template ls
+
+# Get a specific template
+vtriv template get default
+
+# Create/update a template (reads JSON from stdin)
+vtriv template set ai-enabled <<< '{"x-db": true, "x-blob": true, "x-ai": true}'
+
+# Delete a template (cannot delete 'default')
+vtriv template rm ai-enabled
+```
+
+### Database Commands
+
+```bash
+# List documents
+vtriv db ls posts
+vtriv db ls posts --filter '{"status":"published"}' --limit 10 --sort -_created_at
+
+# Get a document
+vtriv db get posts abc-123
+
+# Create a document (reads JSON from stdin)
+echo '{"title":"Hello","body":"World"}' | vtriv db put posts
+
+# Update a document
+echo '{"title":"Updated"}' | vtriv db put posts abc-123
+
+# Delete a document
+vtriv db rm posts abc-123
+
+# Get/set collection schema
+vtriv db schema posts
+echo '{"indexes":["status"],"unique":["slug"]}' | vtriv db schema posts --set
+```
+
+### Blob Commands
+
+```bash
+# Upload a file
+vtriv blob put images/photo.jpg ./local-photo.jpg
+
+# Download a file (outputs to stdout)
+vtriv blob get images/photo.jpg > downloaded.jpg
+
+# Delete a file
+vtriv blob rm images/photo.jpg
+```
+
+### Cron Commands
+
+```bash
+# List jobs
+vtriv cron ls
+
+# View run history
+vtriv cron runs
+vtriv cron runs --limit 50 --job daily-backup
+
+# Manually trigger a job
+vtriv cron trigger daily-backup
+
+# View a script
+vtriv cron script:cat backup.ts
+```
+
+### AI Commands
+
+```bash
+# Simple chat
+vtriv ai chat "What is the capital of France?"
+
+# With specific model
+vtriv ai chat "Explain quantum computing" --model anthropic/claude-3.5-sonnet
+
+# View usage statistics
+vtriv ai stats
+vtriv ai stats --period 7
+
+# Get/set AI config
+vtriv ai config
+vtriv ai config --model openai/gpt-4o --rate-limit 10.0
+```
+
+### Search Commands
+
+```bash
+# Get index configuration
+vtriv search config posts
+
+# Set index configuration (reads JSON from stdin)
+echo '{"model":"openai/text-embedding-3-small","dimensions":1536,"input_fields":["title","body"],"store_fields":["id","title","slug"]}' | vtriv search config posts --set
+
+# Search an index
+vtriv search query posts "semantic search" --limit 20
+```
+
+## Output Formats
+
+By default, the CLI formats output as tables:
+
+```
+$ vtriv db ls posts
+id          title            status
+-----------------------------------------
+abc-123     Hello World      published
+def-456     Draft Post       draft
+```
+
+Use `--json` for machine-readable output:
+
+```bash
+$ vtriv db ls posts --json
+[
+  {"id": "abc-123", "title": "Hello World", "status": "published"},
+  {"id": "def-456", "title": "Draft Post", "status": "draft"}
+]
+```
+
+## Debugging
+
+Use `--debug` to see the curl equivalent of each request:
+
+```bash
+$ vtriv --debug db ls posts
+curl -X GET "http://localhost:3000/db/a1b2c3d4-my-app/posts" -H "Authorization: Bearer <token>"
+```
+
+## Configuration File
+
+The config file at `~/.config/vtriv/config.json`:
+
+```json
+{
+  "baseUrl": "http://localhost:3000",
+  "accountKey": "vtriv_ak_...",
+  "accountSlug": "a1b2c3d4",
+  "default": "my-app",
+  "profiles": {
+    "my-app": {
+      "apiKey": "vtriv_sk_..."
+    },
+    "staging": {
+      "apiKey": "vtriv_sk_..."
+    }
+  }
+}
+```
+
+## Migration from Old Config
 
-## Options
+If you have an old `~/.vtrivrc` file, you'll need to:
+1. Run `vtriv config` with your account key
+2. Run `vtriv init <name>` for each project
 
-- `--json` - Output raw JSON for scripts/agents
-- `--profile <name>` - Use a specific profile
-- `--debug` - Show HTTP curl equivalents
+The old config format is not compatible with the new account-based system.
 
-## Documentation
+## License
 
-See [~/grit/skills/vtriv/cli.md](../../grit/skills/vtriv/cli.md) for full documentation.
+Private - Part of vtriv meta-project