@bagdock/cli 0.3.0 → 0.5.0

package/README.md

@@ -1,3 +1,17 @@
+```
+  ----++                                ----++                    ---+++     
+  ---+++                                ---++                     ---++      
+ ----+---     -----     ---------  --------++ ------     -----   ----++----- 
+ ---------+ --------++----------++--------+++--------+ --------++---++---++++
+ ---+++---++ ++++---++---+++---++---+++---++---+++---++---++---++------++++  
+----++ ---++--------++---++----++---++ ---++---++ ---+---++     -------++    
+----++----+---+++---++---++----++---++----++---++---+++--++ --------+---++   
+---------++--------+++--------+++--------++ -------+++ -------++---++----++  
+ +++++++++   +++++++++- +++---++   ++++++++    ++++++    ++++++  ++++  ++++  
+                     --------+++                                             
+                       +++++++                                               
+```
+
 # @bagdock/cli
 
 The official CLI for Bagdock. Built for humans, AI agents, and CI/CD pipelines.
@@ -16,6 +30,12 @@ curl -fsSL https://bdok.dev/install.sh | bash
 irm https://bdok.dev/install.ps1 | iex
 ```
 
+### Homebrew (macOS / Linux)
+
+```bash
+brew install bagdock/cli/bagdock
+```
+
 ### Node.js
 
 ```bash
@@ -42,12 +62,16 @@ pnpm dlx @bagdock/cli --help
 
 ### Agent skills
 
-This CLI ships with an agent skill that teaches AI coding agents (Cursor, Claude Code, Windsurf, etc.) how to use the Bagdock CLI effectively — including non-interactive flags, output formats, and common pitfalls.
+This CLI ships with an agent skill that teaches AI coding agents (Cursor, Claude Code, Codex, Conductor, etc.) how to use the Bagdock CLI effectively — including non-interactive flags, output formats, and common pitfalls.
+
+To install skills for Bagdock's full platform (API, CLI, adapters) from the central skills repository:
 
 ```bash
 npx skills add bagdock/bagdock-skills
 ```
 
+See [bagdock/bagdock-skills](https://github.com/bagdock/bagdock-skills) for all available skills and plugin manifests.
+
 ## Local development
 
 Use this when you want to change the CLI and run your build locally.
@@ -150,6 +174,42 @@ The CLI resolves your API key using the following priority chain:
 
 If no key is found from any source, the CLI errors with code `auth_error`.
 
+## Environment context
+
+The CLI supports Stripe-style live/test mode switching. Login is universal — you authenticate once, then select which operator and environment to target.
+
+### Operator + environment resolution
+
+| Priority | Source | How to set |
+|----------|--------|-----------|
+| 1 (highest) | `--env` global flag | `bagdock --env test deploy` |
+| 2 | `.bagdock/link.json` | `bagdock link --env test` |
+| 3 | Profile stored value | `bagdock switch` |
+| 4 (lowest) | Default | `live` |
+
+For operator slug:
+
+| Priority | Source | How to set |
+|----------|--------|-----------|
+| 1 (highest) | `BAGDOCK_OPERATOR` env var | `export BAGDOCK_OPERATOR=wisestorage` |
+| 2 (lowest) | Profile stored value | `bagdock switch` or `bagdock login` |
+
+### Typical workflow
+
+```bash
+# Login (universal identity)
+bagdock login
+
+# Select operator and environment
+bagdock switch
+
+# Or override per-command
+bagdock --env test deploy --target staging
+bagdock --env live apps list
+```
+
+All API requests include `X-Environment` and `X-Operator-Slug` headers, ensuring the backend resolves the correct tenant database.
+
 ## Commands
 
 ### `bagdock login`
@@ -236,6 +296,7 @@ bagdock doctor
 |-------|------|------|------|
 | CLI Version | Running latest | Update available or registry unreachable | — |
 | API Key | Key found (shows masked key + source) | — | No key found |
+| Operator Context | Operator + environment set | No operator selected | — |
 | Project Config | Valid `bagdock.json` found | No config or incomplete | — |
 | AI Agents | Lists detected agents (or none) | — | — |
 
@@ -290,6 +351,46 @@ Exits `0` when all checks pass or warn. Exits `1` if any check fails.
 
 ---
 
+### `bagdock switch`
+
+Switch operator and environment context. After login, use this to select which operator (live or sandbox) to target.
+
+```bash
+bagdock switch
+```
+
+#### Interactive mode
+
+```
+? Select operator:
+  1. WiseStorage (wisestorage)
+  2. Ardran REIT (ardran-reit)
+> 1
+
+? Select environment:
+  1. Live
+  2. Sandbox: crm-integration (default)
+  3. Sandbox: access-testing
+> 2
+
+Switched to wisestorage [test] (sandbox: crm-integration)
+```
+
+#### Non-interactive mode (CI/CD)
+
+```bash
+bagdock switch --operator wisestorage --env test
+```
+
+#### JSON output
+
+```bash
+bagdock switch --operator wisestorage --env live --json
+# => {"operator":{"id":"opreg_xxx","slug":"wisestorage","name":"WiseStorage"},"environment":"live"}
+```
+
+---
+
 ### Switch between profiles
 
 If you work across multiple Bagdock operators, the CLI supports named profiles.
@@ -383,6 +484,129 @@ bagdock submit
 
 ---
 
+### `bagdock validate`
+
+Run local pre-submission checks on `bagdock.json` and your bundle before submitting.
+
+```bash
+bagdock validate
+```
+
+Checks performed:
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| bagdock.json | Found and parsed | — | Missing or invalid JSON |
+| Required fields | All present | — | Missing name, slug, version, type, category, or main |
+| Type | Valid type | — | Invalid type value |
+| Kind | — | Unknown kind | — |
+| Entry point | File exists (shows size) | — | File not found |
+| Bundle size | Under 10 MB | Approaching limit (>80%) | Over 10 MB |
+| Project link | — | Slug mismatch with linked project | — |
+
+```bash
+# JSON output
+bagdock validate --json
+# => {"ok":true,"checks":[...]}
+```
+
+Exit code `0` if all checks pass or warn. Exit code `1` if any check fails.
+
+---
+
+### `bagdock submission list`
+
+List submission history for the current app.
+
+```bash
+bagdock submission list
+bagdock submission list --app my-adapter --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--app <slug>` | App slug (defaults to `bagdock.json` or linked project) |
+
+### `bagdock submission status <id>`
+
+Fetch detailed review state for a specific submission.
+
+```bash
+bagdock submission status iadpv_abc123
+bagdock submission status iadpv_abc123 --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--app <slug>` | App slug |
+
+### `bagdock submission withdraw <id>`
+
+Cancel a pending submission before approval. Only works when `review_status` is `submitted`.
+
+```bash
+bagdock submission withdraw iadpv_abc123
+```
+
+| Flag | Description |
+|------|-------------|
+| `--app <slug>` | App slug |
+
+#### Error codes
+
+| Code | Cause |
+|------|-------|
+| `not_found` | Submission or app not found |
+| `invalid_status` | App is not in `submitted` state |
+
+---
+
+### `bagdock open [slug]`
+
+Open the current project in the Bagdock dashboard.
+
+```bash
+bagdock open
+bagdock open my-adapter
+```
+
+Reads the slug from `bagdock.json`, linked project, or the argument.
+
+---
+
+### `bagdock inspect [slug]`
+
+Show deployment details and status for an app.
+
+```bash
+bagdock inspect
+bagdock inspect my-adapter --json
+```
+
+Displays: name, slug, type, version, review status, worker URL, namespace, timestamps.
+
+---
+
+### `bagdock link`
+
+Link the current directory to a Bagdock app or edge. Other commands use the linked slug as a fallback.
+
+```bash
+# Interactive: select from your apps
+bagdock link
+
+# Non-interactive
+bagdock link --slug my-adapter
+```
+
+| Flag | Description |
+|------|-------------|
+| `--slug <slug>` | Project slug (required in non-interactive mode) |
+
+Stores the link in `.bagdock/link.json` in the current directory.
+
+---
+
 ### `bagdock env list`
 
 List environment variables for the current app.
@@ -408,6 +632,17 @@ Remove an environment variable.
 bagdock env remove VENDOR_API_KEY
 ```
 
+### `bagdock env pull [file]`
+
+Pull remote env var keys to a local `.env` file for development.
+
+```bash
+bagdock env pull
+bagdock env pull .env.development
+```
+
+The API does not expose secret values. The file is created with keys and empty values — fill them in for local dev.
+
 ---
 
 ### `bagdock keys create`
@@ -556,6 +791,7 @@ bagdock [global options] <command> [command options]
 |------|-------------|
 | `--api-key <key>` | Override API key for this invocation (takes highest priority) |
 | `-p, --profile <name>` | Profile to use (overrides `BAGDOCK_PROFILE` env var) |
+| `--env <live\|test>` | Override environment for this invocation |
 | `--json` | Force JSON output even in interactive terminals |
 | `-q, --quiet` | Suppress spinners and status output (implies `--json`) |
 | `--version` | Print version and exit |