@dboio/cli 0.11.3 → 0.13.2

package/plugins/claude/dbo/skills/cli/SKILL.md

@@ -1,280 +1,96 @@
 ---
 name: cli
-description: Execute DBO.io CLI commands (pull, push, add, clone, output, input, content, deploy, etc.)
+description: Run DBO.io CLI commands for local file sync, project management, and deployment (push/pull/clone/add/rm/diff/build/deploy). NOT for direct API operations — use docs/ for that.
 user-invokable: true
 ---
 
-# DBO CLI Command
+# DBO CLI Skill
 
-The dbo CLI interacts with DBO.io — a database-driven application framework.
+Run `dbo` CLI commands for local file sync, project management, and deployment.
 
-**STEP 1: Check if `$ARGUMENTS` is empty or blank.**
+## When to use this skill
 
-If `$ARGUMENTS` is empty — meaning the user typed just `/dbo:cli` with nothing after it — then you MUST NOT run any bash command. Do NOT run `dbo`, `dbo --help`, or anything else. Instead, respond ONLY with this text message:
+Use this skill when the user wants to:
+- Run a local workflow command (push, pull, clone, add, rm, diff, build, deploy)
+- Set up a project (`dbo init`, `dbo login`, `dbo clone`)
+- Deploy files to the server (`dbo push`, `dbo deploy`)
 
----
+## When NOT to use this skill
 
-Hi there! I can help you with running dbo commands. What would you like to do?
+Do NOT use this skill for direct API operations. The following CLI commands are thin wrappers around REST endpoints — use the `docs/` reference instead for the canonical API syntax:
+- `dbo input` wraps `POST /api/input/submit` — use `docs/dbo-cheat-sheet.md`
+- `dbo output` wraps `GET /api/output/` — use `docs/dbo-output-query.md`
+- `dbo content` wraps `GET /api/content/` — use `docs/dbo-cheat-sheet.md`
+- `dbo media` wraps `GET /api/media/` — use `docs/dbo-cheat-sheet.md`
+- `dbo upload` wraps `POST /api/upload/submit` — use `docs/dbo-cheat-sheet.md`
+- `dbo message` wraps `GET /api/message/` — use `docs/dbo-cheat-sheet.md`
+- `dbo cache` wraps `/api/cache/` — use `docs/dbo-cheat-sheet.md`
 
-Here are the available commands:
+Also do NOT use this skill for:
+- **Entity schemas / column names** — use `docs/dbo-core-entities.md`
+- **Token/tag syntax** (`#{...}`, `<#_embed>`, etc.) — use `docs/dbo-cheat-sheet.md`
+- **Building server-side templates or content records** — use `docs/`
 
-| Command   | Description                                      |
-|-----------|--------------------------------------------------|
-| init      | Initialize .dbo/ configuration                   |
-| login     | Authenticate with a DBO.io instance              |
-| logout    | Clear session                                    |
-| status    | Show config, domain, and session info            |
-| input     | Submit CRUD operations (add/edit/delete records)  |
-| output    | Query data from outputs or entities              |
-| content   | Get or deploy content                            |
-| media     | Get media files                                  |
-| upload    | Upload a file                                    |
-| message   | Send messages (email, SMS, chatbot)              |
-| pull      | Pull records to local files                      |
-| push      | Push local files back to DBO.io                  |
-| add       | Add a new file to DBO.io                         |
-| clone     | Clone an app to local project structure           |
-| diff      | Compare local files with server versions          |
-| rm        | Remove a file and stage server deletion           |
-| deploy    | Deploy via manifest                              |
-| cache     | Manage cache                                     |
-| install   | Install or upgrade CLI, plugins, Claude commands (shorthand: `i`) |
+All doc files are bundled in the `docs/` subdirectory of this plugin (copied during npm publish). When working in the repo, the API docs are at the repo root `docs/` and the CLI README is at `tools/cli/README.md`.
 
-Just tell me what you'd like to do and I'll help you build the right command!
+For detailed CLI command flags, options, and behavior — read `docs/dbo-cli-readme.md`.
 
----
+## Running commands
 
-Then STOP. Wait for the user to respond. Guide them step by step — asking about entities, UIDs, file paths, flags, etc. to construct the correct `dbo` command. Run `dbo status` proactively to check if the CLI is initialized and authenticated before suggesting data commands.
+**If `$ARGUMENTS` is empty**, show the command table and guide interactively.
 
-**STEP 2: If `$ARGUMENTS` is NOT empty, run the command:**
+**If `$ARGUMENTS` is provided**, run:
 
 ```bash
 dbo $ARGUMENTS
 ```
 
-## Command Reference
-
-Available subcommands:
-- `init` — Initialize .dbo/ configuration for the current directory
-- `login` — Authenticate with a DBO.io instance
-- `logout` — Clear session
-- `status` — Show config, domain, and session info
-- `input -d '<expr>'` — CRUD operations (add/edit/delete records)
-- `output -e <entity>` — Query data from entities
-- `output <uid>` — Query custom outputs
-- `content <uid>` — Get content, `content deploy <uid> <file>` to deploy
-- `pull [uid]` — Pull records to local files (default: content entity)
-- `pull -e <entity> [uid]` — Pull from any entity
-- `push <path>` — Push local files back to DBO using metadata
-- `add <path>` — Add a new file to DBO (creates record on server)
-- `media <uid>` — Get media files
-- `upload <file>` — Upload binary files
-- `message <uid>` — Send messages (email, SMS, chatbot)
-- `cache list|refresh` — Manage cache
-- `clone [source]` — Clone an app to local project (from file or server)
-- `clone --app <name>` — Clone by app short name from server
-- `diff [path]` — Compare local files against server and selectively merge changes
-- `diff -y` — Accept all server changes without prompting
-- `diff --no-interactive` — Show diffs without prompting to accept
-- `rm <file>` — Remove a file locally and stage server deletion for next push
-- `rm <directory>` — Remove a directory, all files, and sub-directories recursively
-- `rm -f <path>` — Remove without confirmation prompts
-- `rm --keep-local <path>` — Stage server deletions without deleting local files/directories
-- `deploy [name]` — Deploy via .dbo/deploy_config.json manifest
-- `install` (alias: `i`) — Install or upgrade CLI, plugins, or Claude commands
-- `i dbo` or `i dbo@latest` — Install/upgrade the CLI from npm
-- `i dbo@0.4.1` — Install a specific CLI version
-- `install /path/to/src` — Install CLI from local source
-- `install plugins` — Install/upgrade Claude command plugins
-- `install plugins --global` — Install plugins to `~/.claude/commands/` (shared across projects)
-- `install plugins --local` — Install plugins to `.claude/commands/` (project only)
-- `install claudecommands` — Install/upgrade Claude Code commands
-- `install claudecode` — Install Claude Code CLI + commands
-- `install --claudecommand dbo --global` — Install a specific command globally
-
-## Change Detection (pull, clone, diff)
-
-When pulling or cloning records that already exist locally, the CLI compares file modification times against the server's `_LastUpdated` timestamp. If the server has newer data, you'll be prompted with options:
-
-1. **Overwrite** — Replace local files with server version
-2. **Compare** — Show a line-by-line diff and selectively merge
-3. **Skip** — Keep local files unchanged
-4. **Overwrite all** — Accept all remaining server changes
-5. **Skip all** — Skip all remaining files
-
-Use `dbo diff [path]` to compare without pulling. Use `-y` to auto-accept all changes.
-
-## Smart Command Building
-
-When helping the user build a command interactively:
-
-1. **Check readiness first**: Run `dbo status` to see if initialized and authenticated. If not, guide them through `dbo init` and `dbo login` first.
-2. **Understand intent**: Ask what they want to do (query data, deploy a file, add a record, etc.)
-3. **Gather parameters**: Ask for the specific values needed (entity name, UID, file path, filters, etc.)
-4. **Build the command**: Construct the full `dbo` command with proper flags and syntax
-5. **Execute**: Run it and explain the results
-
-### Common workflows to suggest:
-
-- **"I want to query data"** → Guide toward `dbo output -e <entity>` with filters
-- **"I want to deploy/update a file"** → Check if `.metadata.json` exists → `dbo push` or `dbo content deploy`
-- **"I want to add a new file"** → `dbo add <path>` (will create metadata interactively)
-- **"I want to pull files from the server"** → `dbo pull` or `dbo pull -e <entity>`
-- **"I want to delete/remove a file"** → `dbo rm <file>` (stages deletion for next `dbo push`)
-- **"I want to delete a directory"** → `dbo rm <directory>` (removes all files + sub-dirs, stages bin deletions)
-- **"I want to see what's on the server"** → `dbo output -e <entity> --format json`
-- **"I need to set up this project"** → `dbo init` → `dbo login` → `dbo status`
-- **"I want to clone an app"** → `dbo clone --app <name>` or `dbo clone <local.json>`
-- **"I want to set up and clone"** → `dbo init --domain <host> --app <name> --clone`
-
-## Add Command Details
-
-`dbo add <path>` registers a new local file with the DBO server by creating an insert record.
-
-```bash
-# Add a single file (interactive metadata wizard if no .metadata.json exists)
-dbo add assets/css/colors.css
-
-# Add with auto-accept and ticket
-dbo add assets/css/colors.css -y --ticket abc123
-
-# Scan current directory for all un-added files
-dbo add .
-
-# Scan a specific directory
-dbo add assets/
-```
-
-Flags: `-C/--confirm <true|false>`, `--ticket <id>`, `-y/--yes`, `--json`, `--jq <expr>`, `-v/--verbose`, `--domain <host>`
-
-### How add works
-
-1. Checks for a companion `<basename>.metadata.json` next to the file
-2. If metadata exists with `_CreatedOn` → already on server, skips (use `push` instead)
-3. If metadata exists without `_CreatedOn` → uses it to insert the record
-4. If no metadata → interactive wizard prompts for: entity, content column, AppID, BinID, SiteID, Path
-5. Creates `.metadata.json`, submits insert to `/api/input/submit`
-6. Writes returned UID back to metadata file
-7. Suggests running `dbo pull -e <entity> <uid>` to populate all server columns
-
-### Non-interactive add (for scripting)
-
-To add without prompts, create the `.metadata.json` first, then run `dbo add <file> -y`:
-
-```json
-{
-  "Name": "colors",
-  "Path": "assets/css/colors.css",
-  "Content": "@colors.css",
-  "_entity": "content",
-  "_contentColumns": ["Content"]
-}
-```
-
-Optional fields like `AppID`, `BinID`, `SiteID` are only included if the user provides values — they have no defaults and are omitted when left blank.
-
-The `@colors.css` value means "read content from colors.css in the same directory".
-
-### Directory scan (`dbo add .`)
+## Command overview
 
-Finds files that have no `.metadata.json` or whose metadata lacks `_CreatedOn`. Skips `.dbo/`, `.git/`, `node_modules/`, dotfiles, and `.metadata.json` files. When adding multiple files, defaults from the first file are reused.
+These are the local workflow commands this skill covers:
 
-## Push Command Details
+| Command | Description |
+|---------|-------------|
+| `init` | Initialize .dbo/ configuration |
+| `login` / `logout` | Authenticate / clear session |
+| `status` | Show config, domain, session info |
+| `clone` | Clone an app to local project |
+| `pull` | Pull records to local files |
+| `push` | Push local changes (default: current dir) |
+| `add` | Add a new file to DBO.io |
+| `diff` | Compare local vs server |
+| `rm` | Remove file, stage server deletion |
+| `deploy` | Deploy via .dbo/deploy_config.json manifest |
+| `build` | Run build hooks (.dbo/scripts.json) |
+| `run` | Run named script (.dbo/scripts.json) |
+| `install` | Install/upgrade CLI, plugins (alias: `i`) |
 
-`dbo push <path>` pushes local file changes back to existing DBO records using their `.metadata.json`.
+## Common workflows
 
 ```bash
-dbo push assets/css/colors.css          # single file
-dbo push assets/                         # all records in directory
-dbo push assets/ --content-only          # only file content, skip metadata
-dbo push assets/ --meta-only             # only metadata columns, skip files
-dbo push assets/ -y --ticket abc123      # auto-accept + ticket
-```
-
-Flags: `-C/--confirm`, `--ticket <id>`, `--meta-only`, `--content-only`, `-y/--yes`, `--json`, `--jq`, `-v/--verbose`, `--domain`
-
-## Column Filtering (add & push)
+# Setup
+dbo init --domain my-domain.com --app myapp --clone
+dbo login
 
-These columns are **never submitted** in add or push payloads:
-- `_CreatedOn`, `_LastUpdated` — server-managed timestamps
-- `_LastUpdatedUserID`, `_LastUpdatedTicketID` — session-provided values
-- `UID` — server-assigned on insert; used as identifier on push (not as column value)
-- `_id`, `_entity`, `_contentColumns`, `_mediaFile` — internal/metadata fields
+# Edit and push
+dbo push                          # push all changes in current dir
+dbo push lib/bins/app/assets/     # push specific directory
+dbo push colors.css               # push single file
 
-## Pull → Edit → Push/Add Workflow
+# Build and push (with script hooks)
+dbo build                         # run build hooks only
+dbo push                          # build + push (hooks run automatically)
+dbo push --no-build               # push without build phase
+dbo push --no-scripts             # push without any hooks
 
-```bash
-# Pull existing records
+# Pull
 dbo pull -e content --filter 'AppID=10100'
 
-# Edit files locally, then push changes back
-dbo push assets/css/colors.css
-
-# Or add a brand new file
+# Add new files
 dbo add assets/css/newstyle.css
-```
-
-## Clone Command Details
+dbo add .                         # scan for un-added files
 
-`dbo clone` scaffolds a local project from a DBO.io app export JSON, creating directories, files, metadata, and config.
-
-```bash
-# Clone from a local JSON export file
-dbo clone /path/to/app_export.json
-
-# Clone from server by app short name (requires login)
-dbo clone --app myapp
-
-# Clone using AppShortName already in config
-dbo clone
-
-# Init + clone in one step
-dbo init --domain my-domain.com --app myapp --clone
+# Compare and merge
+dbo diff                          # compare all local vs server
+dbo diff -y                       # auto-accept all server changes
 ```
-
-Flags: `--app <name>`, `--domain <host>`, `-y/--yes`, `-v/--verbose`
-
-### What clone does
-
-1. Loads app JSON (local file, server API, or prompt)
-2. Updates `.dbo/config.json` with `AppID`, `AppUID`, `AppName`, `AppShortName`
-3. Updates `package.json` with `name`, `productName`, `description`, `homepage`, and `deploy` script
-4. Creates directory structure from `children.bin` hierarchy → saves `.dbo/structure.json`
-5. Writes content files (decodes base64) with `*.metadata.json` into bin directories
-6. Downloads media files from server using fallback chain: FullPath (`/media/{app}/{path}`) → `/dir/` route → `/api/media/{uid}`, with `*.metadata.json`. Errors logged to `.dbo/errors.log`
-7. Processes entity-dir records (`extension`, `app_version`, `data_source`, `site`, `group`, `integration`, `automation`) into `lib/` project directories as `.metadata.json` files with optional companion content files
-8. Processes remaining entities with BinID into corresponding bin directories
-9. Saves `app.json` to project root with `@path/to/*.metadata.json` references
-
-### Placement preferences
-
-When a record has both `Path`/`FullPath` and `BinID`, clone prompts the user to choose placement. Preferences are saved to `.dbo/config.json` and reused on future clones:
-
-- `ContentPlacement`: `bin` | `path` | `ask` — for content and other entities
-- `MediaPlacement`: `bin` | `fullpath` | `ask` — for media files
-
-Pre-set these in config.json to skip prompts. `.dbo/config.json` and `.dbo/structure.json` are shared via git; `.dbo/credentials.json` and `.dbo/cookies.txt` are gitignored (per-user).
-
-### AppID awareness (add & input)
-
-After cloning, the config has an `AppID`. When running `dbo add` or `dbo input` without an AppID in the data, the CLI prompts:
-1. Yes, use AppID from config
-2. No
-3. Enter custom AppID
-
-### Init flags for clone
-
-`dbo init` now supports `--app <shortName>` and `--clone` flags to combine initialization with app cloning.
-
-## Error Handling
-
-- If the command fails with a session/authentication error, suggest: `dbo login`
-- If it fails with "No domain configured", suggest: `dbo init`
-- If a command is not found, suggest: `dbo --help`
-
-## Output
-
-When showing results:
-- Format JSON output readably
-- For pull/push/add operations, list the files created or modified
-- For query operations, summarize the row count and key fields