Skip to content

deckcraft-cli help explains the CLI to an agent - #303

Merged
h-a-n-a-s-h-i merged 4 commits into
storytold:mainfrom
hoblin:feature/help-for-agents
Oct 14, 2026
Merged

h-a-n-a-s-h-i merged 4 commits into
storytold:mainfrom
hoblin:feature/help-for-agents

Conversation

@hoblin

@hoblin hoblin commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Closes #299.

Based on main and stands on its own; it replaces #228.

An AI agent driving deckcraft-cli learns the input language from its help. The help described the CLI in its own grammar: --cmd ID[=JSON], which an agent read as "a label of my own, then =". Nothing said that shape ids are looked up on the current slide, or what format.* acts on. Agents learned those by trial. Now the help explains the CLI in sentences written for a reader, with a full example.

This PR changes the help only. The input language is unchanged.

Before and after

deckcraft-cli --help

before: the usage block, printed as an error.

usage: deckcraft-cli info FILE
       deckcraft-cli render (FILE | --sample) [--slide N | --all] [--scale S] [--edit] OUT
       deckcraft-cli convert IN OUT
       deckcraft-cli run [--in FILE | --sample] [--cmd ID[=JSON]]... [--save OUT] [--export OUT] [--print]
       …

after (help, --help and -h alike):

deckcraft-cli works on DeckCraft presentations (.deckcraft, .pptx) without a window.

  info       print a presentation's slides, layouts and theme as JSON
  render     draw slides as PNG images
  convert    save a presentation in the format OUT's extension names
  run        run commands on a presentation, then save or export it
  commands   list the commands run can use, one per line
  describe   explain one command and its parameters
  app        run a command in the DeckCraft app started with --control
  mcp        serve the commands to an agent over MCP on stdio
  links      print the DeckCraft community and project links
  --version  print the version

A presentation is edited by running commands on it:

  deckcraft-cli run --cmd 'slide.new={"title":"Q3 results"}' --save q3.deckcraft

`deckcraft-cli help SUBCOMMAND`, or `deckcraft-cli SUBCOMMAND --help`, explains one subcommand;
`deckcraft-cli help run` explains commands.

deckcraft-cli run --help

before:

deckcraft-cli: unknown option `--help`

after:

usage: deckcraft-cli run [--in FILE | --sample] [--cmd COMMAND[=PARAMS]]... [--save OUT] [--export OUT] [--print]

Runs commands, in order, on one presentation: FILE with --in, the sample presentation with --sample,
else a new one with an empty title slide. Then --save writes the presentation: .deckcraft keeps
everything; .pptx, .pdf and .md (the outline) are written as convert writes them. --export writes the
current slide as .png or .jpg, or the presentation as .pdf or .pptx.

Each --cmd is one command: COMMAND is a command id, then `=`, then the command's parameters as one
JSON object. Quote it for the shell. A command that needs no parameters is just its id.

  deckcraft-cli run \
    --cmd 'slide.new={"layout":"titleOnly","title":"Q3 results"}' \
    --cmd 'shape.insert={"preset":"roundRect","rect":[80,160,320,120],"text":"Revenue"}' \
    --cmd 'format.size={"size":28}' \
    --save q3.deckcraft

`deckcraft-cli commands` lists the command ids; `deckcraft-cli describe COMMAND` explains one and its
parameters.

What the ids don't say:
- Positions and sizes are in points on a 960×540 slide, x to the right and y down; a rect is
  [x, y, width, height].
- Slide indices start at 0. slide.new inserts after the current slide and makes the new one current;
  slide.go {"index": N} makes slide N current.
- Shape ids are looked up on the current slide only.
- A command that adds a shape (shape.insert, insert.textBox, insert.table…) selects it. format.* acts
  on the selected text or shapes; edit.select {"ids": [...]} selects others. Many shape commands
  take the ids directly; `deckcraft-cli describe COMMAND` says what a command acts on.

If a command fails, run stops there and saves nothing. --print shows each command's answer, such as
the id of an inserted shape.

Every subcommand answers --help and help SUBCOMMAND this way, and does nothing else. Before, render --help rendered a slide into a file named --help, and app --help tried to connect to the app.

deckcraft-cli describe shape.insert / format.size

before:

shape.insert  —  Shapes
  where:    Insert ▸ Illustrations
  shortcut: —
  params:   {preset: rect|roundRect|ellipse|triangle|rightArrow|star5|… (see shape.presets), rect: [x,y,w,h] pt, text?: string}

after:

shape.insert: Shapes, in Insert ▸ Illustrations.

Parameters:
  preset          rect|roundRect|ellipse|triangle|rightArrow|star5|… (see shape.presets)
  rect            [x,y,w,h] pt
  text, optional  string

Run it with: deckcraft-cli run --cmd 'shape.insert={…}'
format.size: Font Size, in Home ▸ Font.

Parameters:
  size  pt
Acts on the selected text or shapes.

Run it with: deckcraft-cli run --cmd 'format.size={…}'

Alternative sets of parameters read as either: / or::

shape.move: Move.

Parameters:
  either:
    dx, optional   pt (relative)
    dy, optional   pt (relative)
    ids, optional
  or:
    x, optional    pt (absolute)
    y, optional    pt (absolute)
    ids, optional
Acts on the shapes in `ids`, else on the selected shapes.

Run it with: deckcraft-cli run --cmd shape.move

A result reads as Answers with {text}., a remark after the parameters as Note: …. "Acts on…" names only the id or ids key the command takes. A command whose parameters are all optional is run by its bare id.

deckcraft-cli commands format.size

before: the full registry entry as pretty JSON, about 8 lines per command. In a session with no presentation, every command printed "enabled": false.

[
  {
    "disabled_reason": "no presentation open",
    "enabled": false,
    "id": "format.size",
    "label": "Font Size",
    "menu": ["Home", "Font"],
    "params": "{size: pt}",
    "shortcut": null
  }
]

after: one line per command; all 226 come to about 16k characters.

format.size — Font Size: {size: pt}

How

  • help.rs holds one entry per subcommand: its usage line, a one-line summary and its own text. The overview, help SUB and SUB --help are all printed from it, and each subcommand's text stands on its own.
  • describe reads the parameters from the command's params doc. parse_params returns each parameter's name, whether it is optional, what the doc says of it, and whether it is an alternative; param_keys lists the keys, and a test requires every params doc to parse.
    • "Acts on…" comes from CommandSpec::acts_on in the engine. It combines the command's availability gate with the id/ids keys it actually takes, and a test checks every command against that.
    • The params docs whose keys shared one unit now give each key its own (shape.move, shape.resize, picture.crop, format.margins, design.slideSize, table.options, table.split). file.export's format is marked optional, as it is in the code, and table.split lists row/col, which it reads. format.color and file.recovery.discard are reworded to fit the grammar. The keys don't change.
  • MCP instructions now say what format.* acts on: the selection, not ids.
  • docs/mcp.md and docs/control-protocol.md carry the current usage (describe COMMAND, app --method METHOD [PARAMS]).

Test plan

  • cargo xtask ci: fmt, clippy, tests, assets, layers, wasm
  • CLI tests:
    • the overview lists every subcommand and has a run example;
    • every subcommand answers --help, -h and help SUB with its usage and writes no file;
    • run --help carries the facts the ids don't;
    • describe output is pinned exactly;
    • commands prints one line per command.
  • Engine tests: parse_params spells out each parameter, including alternatives and remarks; every params doc parses; "Acts on…" names only keys the command takes.
  • Before/after above produced by running main and this branch.

Breaking changes

  • deckcraft-cli commands prints one line per command instead of JSON. MCP's list_commands and the control channel's engine.commands still return JSON.

Overlap

#302 (answers) and #304 (templates) also start from main and touch some of the same lines: params docs, cmd/mod.rs, the ROADMAP log, the end of tests.rs. Whichever lands second, I'll merge main into it. With #302 merged, the run page can mention its OK: line.

[claude-opus-5-5] on behalf of hoblin

`deckcraft-cli help` and each subcommand's `--help` say what it does,
with a working example; `--help` never runs the subcommand. `describe`
spells out a command's parameters and what it acts on, `commands` lists
one command per line, and the MCP instructions say what format.* acts on.

[claude-opus-5-5] on behalf of hoblin
A --cmd without a value now asks for COMMAND[=PARAMS]. The params field
says how describe reads it, table.split's row and col are optional as
the command reads them, and the MCP instructions name only shape
commands for `ids`.

[claude-opus-5-5] on behalf of hoblin
[claude-opus-5-5] on behalf of hoblin
animation.remove's remark belongs to its `ids` option, so describe shows
it there instead of as a note on the whole command. A command with an
all-optional set of parameters is suggested as a bare id.

[claude-opus-5-5] on behalf of hoblin
@h-a-n-a-s-h-i
h-a-n-a-s-h-i merged commit b590cb0 into storytold:main Oct 14, 2026
h-a-n-a-s-h-i pushed a commit that referenced this pull request Oct 14, 2026
…elp pages for bench and render-transition

file.export's slide range and transition.sound's keys parse as parameters, and the subcommands
main added since #303 have their own help page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
h-a-n-a-s-h-i pushed a commit that referenced this pull request Oct 14, 2026
@echelon

echelon commented Oct 14, 2026

Copy link
Copy Markdown
Member

Thank you for this contribution, @hoblin! It has landed on main and will ship in the next DeckCraft release.

If you haven't already, please come join us on Discord: https://discord.gg/artcraft

@hoblin

hoblin commented Oct 14, 2026

Copy link
Copy Markdown
Contributor Author

First of all, thank you for the great tools you've built. I wasn't sure PRs would be merged so I kept other fixes I implemented in my forks. My usual approach is to give an agent new tools, give it a task, look at the tool calls, and fix what failed or was confusing. This way I accumulated many more fixes but it will be hard to merge these into the upstream separately. If you don't mind I'd create combined PRs with the lists of improvements. It would be great to switch agents from my forks to the official repos.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

deckcraft-cli help explains the CLI to an agent

3 participants