# cms-edit — Help Index

`cms-edit` is an opinionated CLI for reading and editing Contentful draft content across SE Studio apps. It provides a snapshot → ref → edit → save workflow. **All writes create drafts — nothing is published automatically.**

---

## How to Get Help

| Command | What you get |
|---|---|
| `cms-edit` | Command list + one-line descriptions |
| `cms-edit <command> --help` | Options and synopsis for a command |
| `cms-edit guide [topic]` | Short getting-started markdown for hosted MCP (`overview`, `workflow`, `commands`, `troubleshooting`, `hosted`) |
| `cms-edit help <topic>` | Detailed CLI playbooks with examples (this index lists topics) |

Available topics for `cms-edit help <topic>`:

| Topic | Contents |
|---|---|
| `workflow` | Standard editing workflow — open, snapshot, edit, save |
| `create-from-json` | Create a new page or article from a JSON file (single-shot) |
| `taxonomy-from-json` | Batch-create tagType, articleType, and tag entries from JSON |
| `person-from-json` | Batch-create person/author entries from JSON |
| `article-tags-from-json` | Set tags on multiple articles from JSON |
| `bulk-rtf-replace` | Find-replace plain text across Rich Text fields in entry trees |
| `batch` | Edit multiple entries by Contentful entry ID, then save once |
| `batch-run` | Execute a JSON script of operations (`batch run --json`) |
| `fields` | Overview of all content types |
| `fields-page` | All fields on a `page` entry |
| `fields-article` | All fields on an `article` entry |
| `fields-component` | All fields on a `component` entry |
| `fields-collection` | All fields on a `collection` entry |
| `fields-taxonomy` | All fields on `tagType`, `articleType`, and `tag` entries |
| `index-sync` | Build and use the local content index (CDA sync) |
| `asset-review` | Visual asset quality review (filename, alt, size, dimensions) |
| `lookup` | Flat flags for `open`, `resolve`, and `nav open` |

---

## Quick-Start One-Liners

```bash
# See what pages exist (catalog index; auto-syncs if needed)
cms-edit list --type page

# Open a page and inspect it
cms-edit open --page-slug /about
cms-edit snapshot

# Edit a field
cms-edit set @c1 heading "New heading"
cms-edit save

# Create a complete new page from a JSON definition
cms-edit create from-json --json '{...}'

# Validate a JSON file without writing anything
cms-edit create from-json --json '{...}' --dry-run

# Bootstrap taxonomy for import scripts
cms-edit create taxonomy-from-json --json '{...}' --if-not-exists

# Import authors from JSON
cms-edit create person-from-json --json '{...}' --if-not-exists

# Bulk retag articles
cms-edit article-tags-from-json --json '{...}'

# Sitewide rich-text find-replace (dry-run first)
cms-edit bulk-rtf-replace --find "Old" --replace-plain "New" --dry-run

# Run a batch of edits
cms-edit batch run --json '[...]'
```

---

## Commands by Category

### Navigation & Discovery

**Content discovery** uses the local catalog index (`index sync`) and `list --type <type>`. Catalog types: `page`, `article`, `pageVariant`, `template`, `articleType`, `tagType`, `tag`, `navigation`, `navigationItem`. Other types (e.g. `person`, `customType`, `pageTest`): `list --type <type> --force-cma`.

| Command | Description |
|---|---|
| `open --page-slug <slug>` | Load a page into the session (see `help lookup`) |
| `open --id <id>` | Load by Contentful entry ID |
| `peek --page-slug <slug>` | Print content tree + root field values without creating a session |
| `peek --id <id>` | Same by Contentful entry ID |
| `snapshot` | Re-print the current session's content tree with @refs |
| `read [@ref] [field]` | Read fields from the active session (@refs from snapshot) |
| `read <id> --id [field]` | Read entry fields by ID without an open session |
| `list --type <ct>` | List catalog entries (page, article, pageVariant, template, taxonomy, nav, …) |
| `search <query>` | Full-text search across entries |
| `resolve <id>` | Resolve a Contentful entry or asset ID |
| `resolve --page-slug <slug>` | Resolve an entry by flat lookup flag (no session); see `help lookup` |
| `create tag-type\|tag\|article-type … --if-not-exists` | Idempotent taxonomy create (returns existing entry if slug matches) |
| `schema types <content-type>` | List valid type-discriminator values |
| `schema colours` | List valid backgroundColour / textColour values |
| `schema <content-type>` | Display field definitions for a content type |
| `health` | Check Contentful API connectivity |

### Editing
| Command | Description |
|---|---|
| `set <ref> <field> <value>` | Set a scalar, link, or array field |
| `rtf <ref> <field> <markdown>` | Set a rich text field from markdown |
| `add <type> <contentType>` | Create and link a new child entry |
| `remove <ref>` | Unlink an entry from its parent |
| `move <ref> <position>` | Reorder an entry in its parent array |
| `links <subcommand>` | Manage CTA link entries |
| `nav <subcommand>` | Manage navigation entries |
| `asset <subcommand>` | Work with assets |

### Session Management
| Command | Description |
|---|---|
| `diff` | Show unsaved changes |
| `save` | Write changes to Contentful as drafts |
| `discard` | Discard unsaved changes |

### Content Creation
| Command | Description |
|---|---|
| `create from-json` | Create a page/article from a JSON file |
| `create taxonomy-from-json` | Batch-create tagType, articleType, and tag entries |
| `create person-from-json` | Batch-create person entries from JSON |
| `create person` | Create a person entry (draft) |
| `article-tags-from-json` | Set tags on articles from JSON |
| `bulk-rtf-replace` | Find-replace in Rich Text across entry trees |
| `create tag-type` | Create a tagType entry (draft) |
| `create article-type` | Create an articleType entry (draft) |
| `create tag` | Create a tag entry (draft) |
| `create page` | Create a blank page interactively |
| `create article` | Create a blank article interactively |

### Batch Operations
| Command | Description |
|---|---|
| `batch set <entryId>:field=value …` | Queue scalar updates on multiple entries by ID |
| `batch diff` / `batch save` / `batch discard` | Review and commit batch session |
| `batch run --json <json> or --json-base64 <encoded>` | Execute a JSON batch of operations |

### Utilities
| Command | Description |
|---|---|
| `asset review` | Audit visual assets (filename, alt, size, dimensions) |
| `preview url` | Generate a page preview URL |
| `preview showcase` | Generate a component/collection showcase URL |
| `preview` | Generate preview URLs |

Agent skills: `npx skills add @se-studio/skills`

---

## Global Options

| Option | Description |
|---|---|
| `--space <name>` | Override the default space from config |
| `--config <path>` | Path to `.contentful-cms.json` |
| `--session <name>` | Named session for concurrent workflows |
| `--json` | Machine-readable JSON output |
| `--docs` | Print path to the full README |

---

## Further Reading

- `cms-edit guide overview` — hosted/MCP getting started
- `cms-edit help workflow` — step-by-step editing guide
- `cms-edit help create-from-json` — single-shot page creation
- `cms-edit help taxonomy-from-json` — batch taxonomy bootstrap
- `cms-edit help fields-taxonomy` — tagType, articleType, and tag field reference
- `cms-edit help batch-run` — JSON operation scripts and variable binding
- `cms-edit help fields-page` — complete page field reference
- `cms-edit --docs` — full README path (for reading in an editor)