---
title: Working with sections
description: The practical outline → get → set loop, addressing sections by anchor, inserting and moving, and reclaiming canvas-edited sections.
---

This guide is the [ordered-sections model](/concepts/sections) as a hands-on workflow — the loop an agent runs to edit a long article without ever handling the whole thing.

## Map before you touch anything

Always start from the outline. It's cheap (no bodies) and prints the anchors you'll use:

```bash
scripto outline <id>
```

```text
  Our launch  [draft] · 1240w

  a1b2c3d4  h1  Our launch                    52w
  e5f6a7b8  h2  What changed                 318w
  9c8d7e6f  h2  Why it matters               210w
```

## Edit one section

An **anchor** is any unique prefix of a section id. Pull a section to a file, edit, push it back:

```bash
scripto section get <id> e5f6a7b8 -o sec.md
# edit sec.md …
scripto section set <id> e5f6a7b8 --file sec.md
```

If the new Markdown contains several headings, that one section **splits into several in place** — and the command echoes the fresh outline so the new anchors are in view.

## Insert a new section

```bash
# Append:
scripto section add <id> --file conclusion.md
# Insert relative to an anchor:
scripto section add <id> --file aside.md --after e5f6a7b8
scripto section add <id> --file intro.md --before a1b2c3d4
echo "## Caveats\n\nText…" | scripto section add <id> --stdin --after 9c8d7e6f
```

Pass exactly one of `--after` / `--before`, or neither to append.

## Move and remove

```bash
scripto section mv <id> 9c8d7e6f --before e5f6a7b8   # reorder
scripto section rm <id> e5f6a7b8                     # delete
```

A section can't be moved relative to itself. Deleting the last remaining section leaves the article with one empty section so it stays editable.

## Anchors that are ambiguous

If a prefix matches more than one section, the command fails with `invalid-argument` and a `nextAction` telling you to use a longer prefix:

```text
✗ The section anchor "a1" is ambiguous.
  next: Use a longer anchor (more characters of the section id).
```

Re-run `scripto outline <id>` to see the current anchors.

## Reclaiming a canvas-edited section

A section the human edited in the web canvas has `source: html` — `section get` returns its HTML and there's no clean Markdown to reverse. To bring it back under Markdown authorship, just `set` it with fresh Markdown:

```bash
scripto section get <id> <anchor>        # inspect the HTML
scripto section set <id> <anchor> --file rewritten.md
```

<Note>

The whole point of the loop is that your context stays proportional to the edit. Resist `scripto articles update <id> --file whole.md` unless you're genuinely replacing the entire body — it re-splits everything and pulls the whole document into context.

</Note>

## Next

- **[The ordered-sections model](/concepts/sections)** — the concept in full.
- **[The section endpoints](/api-reference/add-section)** — the HTTP surface.
- **[Use Scripto with Claude](/guides/with-claude)** — the loop end to end.