# cms-edit — Standard Editing Workflow

The standard workflow is: **open → snapshot → read/edit → diff → save**.

---

## Step 1: Discover What Exists

```bash
# List all pages with slugs
cms-edit list --type page

# Search for entries by text
cms-edit search "hepatology"
```

---

## Step 2: Open a Page or Article

```bash
cms-edit open --page-slug /solutions/hepatology
# or by entry ID:
cms-edit open --id 4xKpzQ2abc123
```

`open` fetches the full entry tree and saves it to a local session file. All subsequent commands operate on this session without re-fetching from Contentful until you `save`.

**Output:**
```
✓ Opened /solutions/hepatology (12 entries)

@c0   page              [draft]    solutions/hepatology
  @c1   component         [draft]    Image Hero
  @c2   component         [draft]    Text Block
  @c3   collection        [draft]    Timeline
    @c4   component         [draft]    Timeline Item 1
    @c5   component         [draft]    Timeline Item 2
  @c6   component         [draft]    Disease Areas
```

---

## Step 3: Inspect the Content Tree

```bash
# Re-print the tree at any time
cms-edit snapshot

# Read all fields on an entry
cms-edit read @c2

# Read a specific field
cms-edit read @c2 heading
```

**Example `read @c2` output:**
```
@c2  component  [draft]  Text Block
  heading:      "Our Approach"
  body:         (rich text, 2 paragraphs)
  backgroundColour: null
```

---

## Step 4: Edit Fields

### Scalar fields (text, boolean, number)
```bash
cms-edit set @c2 heading "New Heading"
cms-edit set @c2 backgroundColour "Navy"
```

### Rich text fields
```bash
# Inline markdown (short content)
cms-edit rtf @c2 body "## Overview\n\nFirst paragraph.\n\nSecond paragraph."

# From a file (long content)
cms-edit rtf @c2 body --content "# ..."
```

### Multi-value: replacing inline content
```bash
# Replace a specific text phrase in a rich text field
cms-edit rtf replace @c2 body --find "old phrase" --replace-plain "new phrase"
```

### Links (CTAs)
```bash
# Add a new external CTA link
cms-edit links add @c2 --type external --label "Learn More" --href "https://example.com"

# Add an internal link (to another page by slug)
cms-edit links add @c2 --type internal --label "Our Team" --slug /team
```

### Adding new entries
```bash
# Add a new component to the page's content array
cms-edit add HeroSimple component

# Add a child item to a collection
cms-edit add Generic component --parent @c3

# Add after a specific entry
cms-edit add Generic component --after @c5
```

**Important:** After any `add` or `remove`, re-run `cms-edit snapshot` — @ref numbers change after structural edits.

---

## Step 5: Review Changes

```bash
cms-edit diff
```

Shows a summary of which entries have been modified and which fields changed.

---

## Step 6: Save

```bash
cms-edit save
```

Writes all changes to Contentful as **drafts**. Nothing is published. A human must review and publish in the Contentful web app.

---

## Common Patterns

### Edit a specific component's heading and body
```bash
cms-edit open --page-slug /about
cms-edit snapshot
cms-edit set @c3 heading "Updated heading"
cms-edit rtf @c3 body "New body text\n\nSecond paragraph."
cms-edit diff
cms-edit save
```

### Add a new section to an existing page
```bash
cms-edit open --page-slug /home
cms-edit snapshot
# Add a new Text Block after @c2
cms-edit add TextBlock component --after @c2
cms-edit snapshot   # re-snapshot to see the new ref
cms-edit set @c3 heading "New Section"
cms-edit rtf @c3 body "Section content.\n\nMore detail."
cms-edit save
```

### Fix a field on multiple pages
Use `--session` to work on multiple pages without losing state:
```bash
cms-edit --session fix-1 open --page-slug /page-one
cms-edit --session fix-1 set @c1 heading "Fixed"
cms-edit --session fix-1 save

cms-edit --session fix-2 open --page-slug /page-two
cms-edit --session fix-2 set @c1 heading "Fixed"
cms-edit --session fix-2 save
```

---

## Creating New Pages

For creating complete new pages with components, use `create from-json` instead of the interactive `add` workflow:

```bash
cms-edit help create-from-json
```

---

## Status Badges

| Badge | Meaning |
|---|---|
| `[published]` | Entry is live in Contentful (no draft changes) |
| `[draft]` | Entry has unpublished changes or has never been published |
| `[changed]` | Entry has been modified in this session (unsaved) |
| `[pending]` | Entry is scheduled for deletion in this session |