@dboio/cli 0.4.1

package/README.md

@@ -0,0 +1,1161 @@
+# dbo — Command Line Interface for DBO.io
+
+A terminal-based CLI for interacting with the [DBO.io](https://dbo.io) framework. Replaces raw curl commands with a clean, subcommand-driven interface for CRUD operations, querying, content deployment, media management, and more.
+
+## Installation
+
+### From the repository (local development)
+
+```bash
+cd tools/dbo-cli
+npm install
+npm link
+```
+
+This makes the `dbo` command available globally on your system.
+
+### From npm (when published)
+
+```bash
+npm install -g @dboio/cli
+```
+
+### Without installing (npx)
+
+```bash
+npx @dboio/cli <command>
+```
+
+### Requirements
+
+- **Node.js 18+** (uses native `fetch` and `FormData`)
+- A DBO.io instance to connect to
+
+## Claude Code Integration
+
+The dbo CLI can be used as a `/dbo` slash command inside Claude Code sessions.
+
+### Install Claude Code commands
+
+```bash
+# Install the /dbo command into your project's .claude/commands/
+dbo install claudecommands
+
+# Or install Claude Code CLI + commands together
+dbo install claudecode
+```
+
+Once installed, use `/dbo` in Claude Code:
+```
+/dbo pull albain3dwkofbhnd1qtd1q
+/dbo output -e user --maxrows 5
+/dbo push assets/css/
+```
+
+The command source lives in `tools/dbo-cli/src/plugins/claudecommands/`. Installed copies in `.claude/commands/` are gitignored and managed by `dbo install` / `dbo update`.
+
+---
+
+## Updating
+
+```bash
+# Update everything (CLI + Claude commands)
+dbo update
+
+# Update only the CLI
+dbo update cli
+
+# Update only Claude Code commands
+dbo update claudecommands
+
+# Update a specific Claude command
+dbo update --claudecommand dbo
+
+# Check your version
+dbo --version
+```
+
+For manual updates:
+
+```bash
+# From git repo
+cd tools/dbo-cli && git pull && npm install
+
+# From npm
+npm update -g @dboio/cli
+```
+
+If you used `npm link`, the link updates automatically — no need to re-link.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Initialize configuration for the current directory
+dbo init --domain beta-dev_model.dbo.io
+
+# 2. Authenticate
+dbo login
+
+# 3. Check your session
+dbo status
+
+# 4. Query some data
+dbo output -e user --format json --maxrows 5
+
+# 5. Deploy a CSS file
+dbo content deploy albain3dwkofbhnd1qtd1q assets/css/colors.css
+```
+
+---
+
+## Configuration
+
+All configuration is **directory-scoped**. Each project folder maintains its own `.dbo/` directory with its own domain and session. Switch environments by switching directories:
+
+```bash
+~/projects/operator-beta/    → .dbo/ → beta-dev_model.dbo.io
+~/projects/operator-prod/    → .dbo/ → prod.dbo.io
+```
+
+### `.dbo/` directory contents
+
+| File | Purpose | Git |
+|------|---------|-----|
+| `config.json` | Domain, app metadata, placement preferences | Committable (shared) |
+| `credentials.json` | Username, user ID, UID, name, email (no password) | Gitignored (per-user) |
+| `cookies.txt` | Session cookie (Netscape format) | Gitignored (per-user) |
+| `structure.json` | Bin directory mapping (created by `dbo clone`) | Committable (shared) |
+
+`dbo init` automatically adds `.dbo/credentials.json` and `.dbo/cookies.txt` to `.gitignore` (creates the file if it doesn't exist).
+
+#### config.json reference
+
+```json
+{
+  "domain": "beta-dev_model.dbo.io",
+  "AppID": 10198,
+  "AppUID": "abc123",
+  "AppName": "My App",
+  "AppShortName": "myapp",
+  "ContentPlacement": "bin",
+  "MediaPlacement": "fullpath"
+}
+```
+
+| Key | Values | Description |
+|-----|--------|-------------|
+| `domain` | hostname | DBO.io instance to connect to |
+| `AppID` | number | App ID (set by `dbo clone`, used by `dbo add`/`dbo input`) |
+| `AppUID` | string | App UID |
+| `AppName` | string | App display name |
+| `AppShortName` | string | App short name (used for `dbo clone --app`) |
+| `ContentPlacement` | `bin` \| `path` \| `ask` | Where to place content files during clone |
+| `MediaPlacement` | `bin` \| `fullpath` \| `ask` | Where to place media files during clone |
+
+**Placement values:**
+- `bin` — Place files in the BinID-mapped directory (from `structure.json`)
+- `path` / `fullpath` — Place files in the Path/FullPath directory from the record
+- `ask` — Prompt for each file that has both a BinID and a Path/FullPath
+
+These are set interactively on first clone and saved for future use. Pre-set them in `config.json` to skip the prompt entirely.
+
+### Legacy migration
+
+If your project uses the older `.domain`, `.username`, `.password`, `.cookies` files, `dbo init` will detect them and offer to migrate automatically.
+
+### Environment variables
+
+Environment variables override file-based configuration:
+
+- `DBO_DOMAIN` — target domain
+- `DBO_USERNAME` — username
+- `DBO_PASSWORD` — password
+
+---
+
+## Commands
+
+### `dbo init`
+
+Initialize DBO CLI configuration for the current directory.
+
+```bash
+dbo init                                          # interactive prompts
+dbo init --domain beta-dev_model.dbo.io           # non-interactive
+dbo init --domain dev.dbo.io --username me@co.io  # with credentials
+dbo init --force                                  # overwrite existing config
+dbo init --domain dev.dbo.io --app myapp --clone  # init + clone an app
+```
+
+| Flag | Description |
+|------|-------------|
+| `--domain <host>` | DBO instance domain |
+| `--username <user>` | DBO username (stored for login default) |
+| `--force` | Overwrite existing configuration |
+| `--app <shortName>` | App short name (triggers clone after init) |
+| `--clone` | Clone the app after initialization |
+
+---
+
+### `dbo clone`
+
+Clone an app from DBO.io to a local project structure. Creates directories, files, metadata, and populates `config.json` and `package.json`.
+
+```bash
+# Clone using config (AppShortName from .dbo/config.json)
+dbo clone
+
+# Clone from a local JSON export file
+dbo clone /path/to/app_export.json
+
+# Clone from server by app short name
+dbo clone --app myapp
+
+# Combined with init
+dbo init --domain beta-dev.dbo.io --app myapp --clone
+```
+
+| Flag | Description |
+|------|-------------|
+| `<source>` | Local JSON file path (optional positional argument) |
+| `--app <name>` | App short name to fetch from server |
+| `--domain <host>` | Override domain |
+| `-y, --yes` | Auto-accept all prompts |
+| `-v, --verbose` | Show HTTP request details |
+
+#### What clone does
+
+1. **Loads app JSON** — from a local file, server API, or interactive prompt
+2. **Updates `.dbo/config.json`** — saves `AppID`, `AppUID`, `AppName`, `AppShortName`
+3. **Updates `package.json`** — populates `name`, `productName`, `description`, `homepage`, and `deploy` script
+4. **Creates directories** — processes `children.bin` to build the directory hierarchy based on `ParentBinID` relationships
+5. **Saves `.dbo/structure.json`** — maps BinIDs to directory paths for file placement
+6. **Writes content files** — decodes base64 content, creates `*.metadata.json` + content files in the correct bin directory
+7. **Downloads media files** — fetches binary files (images, CSS, fonts) from the server via `/api/media/{uid}` and saves with metadata
+8. **Processes other entities** — entities with a `BinID` are placed in the corresponding directory
+9. **Saves `app.json`** — clone of the original JSON with processed entries replaced by `@path/to/*.metadata.json` references
+
+#### Path resolution
+
+When a content record has both `Path` and `BinID`, the CLI prompts:
+```
+Where do you want me to place filename.ext?
+  1. Into the Path of /path/from/path/column
+  2. Into the BinID of 12345 (mapped BinName → bin/directory)
+```
+
+#### Output structure
+
+```
+project/
+  .dbo/
+    config.json              # Updated with app metadata
+    structure.json           # Bin directory mapping
+  .gitignore                 # credentials.json + cookies.txt added
+  package.json               # Updated with app info + deploy script
+  app.json                   # Clone of original with @references
+  bins/                      # ← root for all bin-placed files
+    app/                     # ← directory from children.bin
+      thomas-scratch.md
+      thomas-scratch.metadata.json
+      CurrentTicketID.cs
+      CurrentTicketID.metadata.json
+    ticket_test/             # ← another bin directory
+      ...
+  media/operator/app/...     # ← FullPath placement (when MediaPlacement=fullpath)
+```
+
+---
+
+### `dbo login`
+
+Authenticate with a DBO.io instance and store the session cookie.
+
+After successful authentication, the CLI automatically fetches and stores the current user's ID, UID, name, and email in `.dbo/credentials.json`. The ID and UID are used for automatic retry when server submissions require user identity (see [Automatic error recovery](#automatic-error-recovery)). The name and email are used to populate `package.json` author fields during `dbo clone`.
+
+> **Note:** User info is currently retrieved via a separate API call after login. This is a temporary workaround — the authentication endpoint should include user info in its response directly.
+
+```bash
+dbo login                                         # uses stored credentials
+dbo login -u user@example.com -p myPassword       # explicit credentials
+dbo login -e user@example.com                     # authenticate by email
+dbo login --phone +15551234567 -p myPassword      # authenticate by phone
+dbo login --passkey abc123def                     # authenticate with passkey
+```
+
+| Flag | Description |
+|------|-------------|
+| `-u, --username <value>` | Username identity |
+| `-e, --email <value>` | Email identity |
+| `--phone <value>` | Phone number identity |
+| `-p, --password <value>` | Password credential |
+| `--passkey <value>` | Passkey credential (rotating API key) |
+| `--domain <host>` | Override domain for this request |
+
+---
+
+### `dbo logout`
+
+Log out and clear the local session cookie.
+
+```bash
+dbo logout
+```
+
+---
+
+### `dbo status`
+
+Show current configuration, domain, and session status.
+
+```bash
+dbo status
+```
+
+Output:
+```
+  Initialized: Yes (.dbo/)
+  Domain: beta-dev_model.dbo.io
+  Username: user@example.com
+  User ID: 10296
+  User UID: albain3dwkofbhnd1qtd1q
+  Directory: /Users/me/projects/operator
+  Session: Active (expires: 2026-03-15T10:30:00.000Z)
+  Cookies: /Users/me/projects/operator/.dbo/cookies.txt
+```
+
+User ID and UID are populated by `dbo login`. If they show "(not set)", run `dbo login` to fetch them.
+
+---
+
+### `dbo input`
+
+Submit CRUD operations (add, edit, delete records) to DBO.io. This is the core data manipulation command.
+
+```bash
+# Add a record
+dbo input -d 'RowID:add1;column:user.FirstName=John' -d 'RowID:add1;column:user.LastName=Doe'
+
+# Edit a record by UID
+dbo input -d 'RowUID:albain3dwkofbhnd1qtd1q;column:content.Content@assets/css/colors.css'
+
+# Delete a record
+dbo input -d 'RowID:del10062;entity:user=true'
+
+# Multiple operations in one call
+dbo input -d 'RowID:add1;column:user.LastName=Doe&RowUID:abc;column:content.Content@file.css'
+
+# With file upload (multipart)
+dbo input -d 'RowID:add1;column:media.BinID=12345' -f file=@path/to/image.jpg
+
+# Validation only (no commit)
+dbo input -d 'RowID:add1;column:user.FirstName=John' --confirm false
+
+# With ticket ID override
+dbo input -d 'RowID:add1;column:content.Name=test' --ticket abc123
+
+# See the HTTP request being made
+dbo input -d 'RowUID:abc;column:content.Content@file.css' -v
+```
+
+| Flag | Description |
+|------|-------------|
+| `-d, --data <expr>` | DBO input expression (repeatable) |
+| `-f, --file <field=@path>` | File attachment for multipart upload (repeatable) |
+| `-C, --confirm <true\|false>` | Commit changes (default: `true`). Use `false` for validation only |
+| `--ticket <id>` | Override ticket ID (`_OverrideTicketID`) |
+| `--login` | Auto-login user created by this submission |
+| `--transactional` | Use transactional processing |
+| `--json` | Output raw JSON response |
+| `-v, --verbose` | Show HTTP request details |
+| `--domain <host>` | Override domain |
+
+#### Input expression syntax
+
+```
+RowID:identifier;column:entity.ColumnName=value       # direct value
+RowUID:identifier;column:entity.ColumnName@filepath    # value from file
+RowID:delIdentifier;entity:entityName=true             # delete
+```
+
+The `@filepath` syntax reads the file contents and uses them as the column value. This is how CSS, JS, HTML, and other text content is deployed to DBO.
+
+---
+
+### `dbo output`
+
+Query data from DBO.io outputs or entities.
+
+```bash
+# Custom output by UID
+dbo output qfkyyp2vxeaggdeo7dwbig
+
+# Entity query
+dbo output -e user --format json
+
+# Single record
+dbo output -e user --row 10296
+
+# With filtering and sorting
+dbo output -e user --filter 'FirstName=John' --sort 'LastName:asc' --format json
+
+# Contains filter
+dbo output -e content --filter 'Name:contains=color' --format json
+
+# Pagination
+dbo output -e user --page 2 --rows-per-page 25
+
+# Save results to local files (interactive)
+dbo output -e content --filter 'AppID=10100' --save
+
+# Save results to local files (non-interactive / scripting)
+dbo output -e content --save-filename Name --save-path Path --save-content Content --save-extension Extension
+
+# Entity metadata
+dbo output -e user --meta
+
+# Debug SQL
+dbo output myOutputUID --debug-sql
+```
+
+| Flag | Description |
+|------|-------------|
+| `<uid>` | Output UID (positional argument) |
+| `-e, --entity <uid>` | Query by entity UID |
+| `--row <id>` | Specific row ID |
+| `--filter <expr>` | Filter expression (repeatable) |
+| `--format <type>` | Output format: `json`, `html`, `csv`, `xml`, `txt`, `pdf` |
+| `--sort <expr>` | Sort expression (repeatable), e.g., `LastName:asc` |
+| `--search <expr>` | Full-text search |
+| `--page <n>` | Page number |
+| `--rows-per-page <n>` | Rows per page |
+| `--maxrows <n>` | Maximum rows |
+| `--rows <range>` | Row range, e.g., `1-10` |
+| `--template <value>` | Custom template |
+| `--debug` | Include debug info |
+| `--debug-sql` | Include SQL debug info |
+| `--meta` | Use meta output endpoint |
+| `--meta-column <uid>` | Column metadata |
+| `--save` | Interactive save-to-disk mode |
+| `--save-filename <col>` | Column for filenames (non-interactive) |
+| `--save-path <col>` | Column for file path (non-interactive) |
+| `--save-content <col>` | Column for file content (non-interactive) |
+| `--save-extension <col>` | Column or literal extension (non-interactive) |
+| `--json` | Output raw JSON |
+| `-v, --verbose` | Show HTTP request details |
+
+#### Save to Disk (`--save`)
+
+The save-to-disk feature fetches data and persists records as local files. It uses an interactive flow with arrow-key selection prompts:
+
+1. **Filename column** — which column value becomes the filename (default: `Name` or `UID`)
+2. **Path column** — which column contains the directory path (builds local directories)
+3. **Content column(s)** — which column(s) to save as file content (skip for metadata only)
+4. **Extension** — use an entity column or specify manually
+
+Each record produces:
+- A content file: `[filename].[extension]`
+- A metadata file: `[filename].metadata.json` (all column values)
+
+If the path column contains a filename (e.g., `assets/js/main.js`), the CLI detects it and asks if you want to use it.
+
+---
+
+### `dbo content`
+
+Get, deploy, or pull content from DBO.io.
+
+```bash
+# Get content by UID
+dbo content ykqucv0eb0ggjqgcncj6dq
+
+# Save content to a local file
+dbo content ykqucv0eb0ggjqgcncj6dq -o local/file.html
+
+# Get as plain text (disable minification)
+dbo content ykqucv0eb0ggjqgcncj6dq --format txt --no-minify
+```
+
+| Flag | Description |
+|------|-------------|
+| `<uid>` | Content UID |
+| `-o, --output <path>` | Save to local file |
+| `--format <type>` | Output format |
+| `--no-minify` | Disable minification |
+| `--json` | Output raw JSON |
+
+#### `dbo content deploy`
+
+Deploy a local file's contents to a DBO content record.
+
+```bash
+dbo content deploy albain3dwkofbhnd1qtd1q assets/css/colors.css
+dbo content deploy rncjivlghu65bmkbjnxynq assets/js/app.js
+dbo content deploy abc123 docs/readme.md --ticket myTicket
+dbo content deploy abc123 test.html --confirm false    # validate only
+```
+
+This is a shorthand for:
+```bash
+dbo input -d 'RowUID:albain3dwkofbhnd1qtd1q;column:content.Content@assets/css/colors.css'
+```
+
+| Flag | Description |
+|------|-------------|
+| `<uid>` | Content UID (RowUID) |
+| `<filepath>` | Local file path |
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+| `--ticket <id>` | Override ticket ID |
+
+#### `dbo content pull`
+
+Pull content records from DBO to local files. Uses the content entity's well-known columns (`Name`, `Path`, `Content`, `Extension`) automatically — no interactive prompts.
+
+```bash
+# Pull a single content record
+dbo content pull ykqucv0eb0ggjqgcncj6dq
+
+# Pull all content for an app
+dbo content pull --filter 'AppID=10100'
+
+# Pull with row limit
+dbo content pull --filter 'AppID=10100' --maxrows 50
+```
+
+Creates local files matching the content entity's `Path` and `Extension` columns:
+```
+css/
+  colors.css                    # content.Content value
+  colors.metadata.json          # all column values as JSON
+js/
+  app.js
+  app.metadata.json
+```
+
+---
+
+### `dbo media`
+
+Get media files from DBO.io.
+
+```bash
+# Get media by UID
+dbo media albain3dwkofbhnd1qtd1q
+
+# Save to local file
+dbo media albain3dwkofbhnd1qtd1q -o logo.png
+
+# Get by numeric ID
+dbo media --id 12345 -o file.jpg
+
+# Get by path
+dbo media --path assets/images/logo.png -o logo.png
+
+# Force download
+dbo media albain3dwkofbhnd1qtd1q --download -o file.pdf
+```
+
+| Flag | Description |
+|------|-------------|
+| `<uid>` | Media UID |
+| `--id <id>` | Media by numeric ID |
+| `--path <path>` | Media by directory path |
+| `-o, --output <path>` | Save to local file |
+| `--download` | Force download (attachment disposition) |
+
+---
+
+### `dbo upload`
+
+Upload a binary file to DBO.io.
+
+```bash
+dbo upload image.jpg --bin 12345 --app 67890 --ownership app --path assets/images
+dbo upload logo.svg --bin 12345 --app 67890 --ownership app --path assets/gfx --name brand-logo
+dbo upload doc.pdf --bin 12345 --app 67890 --ownership user --path docs --confirm false
+```
+
+| Flag | Description |
+|------|-------------|
+| `<filepath>` | Local file to upload |
+| `--bin <id>` | BinID (required) |
+| `--app <id>` | AppID (required) |
+| `--ownership <type>` | Ownership: `app`, `user`, or `system` (required) |
+| `--path <dir>` | Media path (required) |
+| `--name <value>` | Override filename |
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+
+---
+
+### `dbo message`
+
+Send messages via DBO.io (email, SMS/MMS, chatbot).
+
+```bash
+# Send an email
+dbo message emailTemplateUID
+
+# Send a chatbot message with thread
+dbo message chatbotTemplateUID --thread conversation123
+
+# Validate without sending
+dbo message emailTemplateUID --confirm false
+```
+
+| Flag | Description |
+|------|-------------|
+| `<uid>` | Content UID for the message template |
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+| `--thread <id>` | Thread ID for chatbot conversations |
+| `--json` | Output raw JSON |
+
+---
+
+### `dbo cache`
+
+Manage the DBO.io cache.
+
+```bash
+# List all cached items
+dbo cache list
+
+# List with metadata
+dbo cache list --metadata
+
+# Refresh a specific cache key
+dbo cache refresh --key 'content:myContentUID'
+```
+
+#### `dbo cache list`
+
+| Flag | Description |
+|------|-------------|
+| `--metadata` | Include cache provider metadata |
+| `--json` | Output raw JSON |
+
+#### `dbo cache refresh`
+
+| Flag | Description |
+|------|-------------|
+| `--key <value>` | Cache key to refresh (required) |
+| `--part <value>` | Cache partition |
+
+---
+
+### `dbo instance`
+
+Manage DBO.io instances.
+
+```bash
+# Export the current instance
+dbo instance export
+
+# Build an instance
+dbo instance build instanceUID
+
+# Validate without executing
+dbo instance export --confirm false
+```
+
+#### `dbo instance export`
+
+| Flag | Description |
+|------|-------------|
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+
+#### `dbo instance build <uid>`
+
+| Flag | Description |
+|------|-------------|
+| `<uid>` | Instance UID |
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+
+---
+
+### `dbo push`
+
+Push local files back to DBO.io using metadata from a previous pull. This is the counterpart to `dbo content pull` and `dbo output --save`.
+
+#### Round-trip workflow
+
+```bash
+# 1. Pull content to local files
+dbo content pull --filter 'AppID=10100' --maxrows 10
+
+# 2. Edit files locally
+vim css/colors.css
+
+# 3. Push changes back to DBO
+dbo push css/colors.css
+```
+
+#### Single file
+
+```bash
+# Push a single file (uses companion .metadata.json)
+dbo push assets/js/main.js
+
+# Validate without submitting
+dbo push assets/js/main.js --confirm false
+
+# Push only the file content, not metadata columns
+dbo push assets/js/main.js --content-only
+
+# Push only metadata changes, skip file content
+dbo push assets/js/main.js --meta-only
+```
+
+The push command finds `assets/js/main.metadata.json`, reads the UID and entity, and builds input expressions for all columns.
+
+#### Directory (recursive)
+
+```bash
+# Push all records in a directory
+dbo push assets/
+
+# Push with auto-accept for all prompts
+dbo push assets/ -y
+```
+
+Recursively finds all `*.metadata.json` files, verifies `@filename` references exist, and pushes each record.
+
+#### Path mismatch detection
+
+If you move a file to a different directory after pulling, the push detects the mismatch:
+
+```
+  ⚠ Path mismatch for "main":
+    Metadata Path: css/main.css
+    Current path:  assets/css/main.css
+  Update Path column to "assets/css/main.css"? (Y/n)
+```
+
+The `--yes` flag auto-accepts path updates.
+
+#### Metadata format
+
+After a pull, metadata files contain `@filename` references for content columns:
+
+```json
+{
+  "_entity": "content",
+  "_contentColumns": ["Content"],
+  "UID": "abc123",
+  "Name": "colors",
+  "Content": "@colors.css",
+  "Extension": "CSS",
+  "Path": "css/colors.css",
+  "Type": "Code"
+}
+```
+
+The `@colors.css` reference tells push to read the content from that file. All other values are pushed as literal column values.
+
+| Flag | Description |
+|------|-------------|
+| `<path>` | File or directory to push |
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+| `--ticket <id>` | Override ticket ID |
+| `--meta-only` | Only push metadata, skip file content |
+| `--content-only` | Only push file content, skip metadata |
+| `-y, --yes` | Auto-accept all prompts |
+| `--json` | Output raw JSON |
+| `--jq <expr>` | Filter JSON response |
+
+---
+
+### `dbo add`
+
+Add a new file to DBO.io by creating a server record. Similar to `git add`, this registers a local file with the server.
+
+#### Single file
+
+```bash
+# Add a file (interactive metadata setup if no .metadata.json exists)
+dbo add assets/css/colors.css
+
+# Add with auto-accept prompts
+dbo add assets/css/colors.css -y
+
+# Add with ticket ID
+dbo add assets/css/colors.css --ticket abc123
+```
+
+If the file has no companion `.metadata.json`, an interactive wizard prompts for the entity name, content column, AppID, BinID, SiteID, and Path. It then creates the metadata file and submits the insert.
+
+#### Directory scan
+
+```bash
+# Scan current directory for un-added files
+dbo add .
+
+# Scan a specific directory
+dbo add assets/
+```
+
+Recursively finds files that either have no `.metadata.json` companion or have metadata without `_CreatedOn` (never been on the server). Lists them and prompts for confirmation before adding.
+
+When adding multiple files, the entity and column defaults from the first file are reused for subsequent files.
+
+#### After adding
+
+After a successful add, the server returns a UID which is written back to the metadata file. To populate all server-side columns (like `_CreatedOn`, `Extension`, etc.), run:
+
+```bash
+dbo pull -e content <uid>
+```
+
+#### Metadata generated by add
+
+Minimal (no optional fields provided):
+```json
+{
+  "Name": "colors",
+  "Path": "assets/css/colors.css",
+  "Content": "@colors.css",
+  "_entity": "content",
+  "_contentColumns": ["Content"]
+}
+```
+
+With optional fields (only included if the user provides values during the wizard):
+```json
+{
+  "AppID": 10100,
+  "BinID": 11045,
+  "SiteID": 10061,
+  "Name": "colors",
+  "Path": "assets/css/colors.css",
+  "Content": "@colors.css",
+  "_entity": "content",
+  "_contentColumns": ["Content"]
+}
+```
+
+The `@colors.css` reference tells the CLI to read the file content from `colors.css` in the same directory.
+
+| Flag | Description |
+|------|-------------|
+| `<path>` | File or `.` to scan current directory |
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+| `--ticket <id>` | Override ticket ID |
+| `-y, --yes` | Auto-accept all prompts |
+| `--json` | Output raw JSON |
+| `--jq <expr>` | Filter JSON response |
+
+#### Column filtering
+
+The `add` and `push` commands never submit these server-managed columns:
+- `_CreatedOn`, `_LastUpdated` — set by the server
+- `_LastUpdatedUserID`, `_LastUpdatedTicketID` — session-provided values
+- `UID` — assigned by the server on insert
+- `_id` — internal database ID
+
+---
+
+### Automatic error recovery
+
+The `input`, `push`, and `add` commands automatically detect recoverable server errors and prompt for missing values instead of failing immediately.
+
+#### Ticket ID required
+
+When the server returns `ticket_lookup_required_error`, the CLI prompts:
+
+```
+⚠ This operation requires a Ticket ID.
+? Ticket ID Required: ___
+```
+
+The submission is then retried with `_OverrideTicketID`. To skip the prompt, pass `--ticket <id>` upfront.
+
+#### User identity required
+
+When the server returns an error mentioning `LoggedInUser_UID`, `LoggedInUserID`, `CurrentUserID`, or `UserID`, the CLI checks for a stored user identity from `dbo login`:
+
+```
+⚠ This operation requires an authenticated user (LoggedInUser_UID).
+  Your session may have expired, or you may not be logged in.
+  You can log in with "dbo login" to avoid this prompt in the future.
+  Stored session user UID: albain3dwkofbhnd1qtd1q
+? User UID Required:
+❯ Use session user (UID: albain3dwkofbhnd1qtd1q)
+  Enter a different User UID
+```
+
+If no stored user info is available, it prompts for direct input. The CLI automatically determines whether the server needs a UID or numeric ID based on the error message pattern.
+
+---
+
+### `dbo install`
+
+Install dbo-cli components including Claude Code integration.
+
+```bash
+# Interactive — choose what to install
+dbo install
+
+# Install Claude Code commands into .claude/commands/
+dbo install claudecommands
+
+# Install Claude Code CLI (if not present) + commands
+dbo install claudecode
+
+# Install a specific command plugin
+dbo install --claudecommand dbo
+```
+
+| Flag | Description |
+|------|-------------|
+| `[target]` | What to install: `claudecode`, `claudecommands` |
+| `--claudecommand <name>` | Install a specific command by name |
+
+When installing Claude commands:
+- Creates `.claude/commands/` if it doesn't exist (prompts first)
+- Prompts before overwriting existing commands
+- Adds installed files to `.gitignore` (source of truth is `src/plugins/claudecommands/`)
+
+---
+
+### `dbo update`
+
+Update the dbo CLI, plugins, or Claude Code commands.
+
+```bash
+# Update CLI + ask about Claude commands
+dbo update
+
+# Update only the CLI (git pull or npm update)
+dbo update cli
+
+# Update all plugins
+dbo update plugins
+
+# Re-sync Claude commands from source
+dbo update claudecommands
+
+# Update a specific Claude command
+dbo update --claudecommand dbo
+```
+
+| Flag | Description |
+|------|-------------|
+| `[target]` | What to update: `cli`, `plugins`, `claudecommands` |
+| `--claudecommand <name>` | Update a specific command by name |
+
+The update compares file hashes — unchanged files are skipped with "already up to date".
+
+---
+
+### `dbo deploy`
+
+Deploy files to DBO.io using a `dbo.deploy.json` manifest or direct arguments.
+
+```bash
+# Deploy a named entry from the manifest
+dbo deploy css:colors
+
+# Deploy all entries
+dbo deploy --all
+
+# Deploy with ticket ID
+dbo deploy js:app --ticket abc123
+
+# Validate without deploying
+dbo deploy css:colors --confirm false
+```
+
+| Flag | Description |
+|------|-------------|
+| `<name>` | Deployment name from `dbo.deploy.json` |
+| `--all` | Deploy all entries in the manifest |
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+| `--ticket <id>` | Override ticket ID |
+
+#### `dbo.deploy.json` manifest
+
+Create a `dbo.deploy.json` file in your project root to define named deployments:
+
+```json
+{
+  "deployments": {
+    "css:colors": {
+      "uid": "albain3dwkofbhnd1qtd1q",
+      "file": "assets/css/colors.css"
+    },
+    "js:app": {
+      "uid": "rncjivlghu65bmkbjnxynq",
+      "file": "assets/js/app.js"
+    },
+    "doc:colors": {
+      "uid": "l2uv2gu8gu6ziyluuncv0w",
+      "file": "docs/colors.md",
+      "entity": "extension",
+      "column": "Text"
+    }
+  }
+}
+```
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `uid` | Target record UID (required) | — |
+| `file` | Local file path (required) | — |
+| `entity` | Target entity name | `content` |
+| `column` | Target column name | `Content` |
+
+This replaces the curl commands typically embedded in `package.json` scripts.
+
+---
+
+## Global Flags
+
+These flags are available on most commands:
+
+| Flag | Description |
+|------|-------------|
+| `-C, --confirm <true\|false>` | Commit changes (default: `true`). Use `false` for validation only |
+| `--json` | Output raw JSON response with syntax highlighting |
+| `--jq <expr>` | Filter JSON response with a jq-like expression (implies `--json`) |
+| `-v, --verbose` | Show HTTP request details (method, URL, body) |
+| `--domain <host>` | Override the configured domain for this request |
+| `-h, --help` | Show help for any command |
+
+---
+
+## JSON Filtering (`--jq`)
+
+The `--jq` flag provides built-in jq-like JSON filtering without requiring `jq` to be installed. It supports the most common patterns:
+
+```bash
+# Pretty-print the entire response (with syntax highlighting)
+dbo output -e user --jq '.'
+
+# Extract a specific key
+dbo output -e user --jq '.Payload'
+
+# Nested key access
+dbo input -d '...' --jq '.Payload.Results.Add'
+
+# Pluck a field from every item in an array
+dbo output -e user --jq '.Payload.Results.Add[].UID'
+
+# Array index
+dbo output -e user --jq '.Payload.Results.Add[0]'
+
+# Pipe: iterate then access
+dbo output -e user --jq '.Payload.Results.Add[] | .UID'
+
+# Use with any command that returns JSON
+dbo cache list --jq '.Payload'
+dbo message myUID --jq '.Successful'
+```
+
+### Supported expressions
+
+| Expression | Description |
+|-----------|-------------|
+| `.` | Identity (entire response) |
+| `.key` | Access a top-level key |
+| `.key.nested` | Nested key access |
+| `.[0]` | Array index |
+| `.[]` | Iterate array |
+| `.[].field` | Pluck field from each array item |
+| `.[] \| .field` | Pipe: iterate then access |
+| `.["key.name"]` | Bracket notation for keys with dots |
+
+When `--jq` is used, the API request is automatically made with `_format=json`.
+
+### JSON syntax highlighting
+
+Both `--json` and `--jq` output use syntax highlighting:
+- **Keys** in cyan
+- **Strings** in green
+- **Numbers** in yellow
+- **Booleans/null** in magenta
+
+---
+
+## Migration from curl
+
+The `dbo` CLI is a drop-in replacement for the curl-based workflow. Here's how common operations translate:
+
+### Authentication
+
+**Before:**
+```bash
+echo "beta-dev_model.dbo.io" > .domain
+echo "user@example.com" > .username
+echo "mypassword" > .password
+curl --cookie-jar .cookies -K authenticate.curl
+```
+
+**After:**
+```bash
+dbo init --domain beta-dev_model.dbo.io --username user@example.com
+dbo login
+```
+
+### Edit a record
+
+**Before:**
+```bash
+curl -K config-data.curl -d "RowID:10065;column:user.FirstName=Jane"
+```
+
+**After:**
+```bash
+dbo input -d 'RowID:10065;column:user.FirstName=Jane'
+```
+
+### Deploy CSS from a local file
+
+**Before:**
+```bash
+curl -K config-data.curl --data-urlencode RowUID%3Aalbain3dwkofbhnd1qtd1q%3Bcolumn%3Acontent.Content@assets/css/colors.css
+```
+
+**After:**
+```bash
+dbo content deploy albain3dwkofbhnd1qtd1q assets/css/colors.css
+```
+
+### Upload a media file
+
+**Before:**
+```bash
+curl -K config-form.curl -F file=@path/to/image.jpg -F "RowID:add1;column:media.BinID=12345" -F "RowID:add1;column:media.AppID=67890" -F "RowID:add1;column:media.Ownership=app" -F "RowID:add1;column:media.Path=assets/images"
+```
+
+**After:**
+```bash
+dbo upload image.jpg --bin 12345 --app 67890 --ownership app --path assets/images
+```
+
+### Query data
+
+**Before:**
+```bash
+curl -b .cookies "https://beta-dev_model.dbo.io/api/output/entity/user?_format=json&_filter@FirstName=John"
+```
+
+**After:**
+```bash
+dbo output -e user --filter 'FirstName=John' --format json
+```
+
+### Cookie compatibility
+
+The `dbo` CLI writes cookies in Netscape format (same as curl's `--cookie-jar`). You can use the same cookie file with both tools during migration:
+
+```bash
+dbo login
+curl -b .dbo/cookies.txt https://beta-dev_model.dbo.io/api/content/myUID
+```
+
+---
+
+## License
+
+Copyright manolab, LLC