Repository navigation
deckcraft-cli help explains the CLI to an agent - #303
Merged
Merged
Conversation
`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
This was referenced Oct 12, 2026
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
3 of 4 tasks
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>
Member
|
Thank you for this contribution, @hoblin! It has landed on If you haven't already, please come join us on Discord: https://discord.gg/artcraft |
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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #299.
Based on
mainand stands on its own; it replaces #228.An AI agent driving
deckcraft-clilearns 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 whatformat.*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 --helpbefore: the usage block, printed as an error.
after (
help,--helpand-halike):deckcraft-cli run --helpbefore:
after:
Every subcommand answers
--helpandhelp SUBCOMMANDthis way, and does nothing else. Before,render --helprendered a slide into a file named--help, andapp --helptried to connect to the app.deckcraft-cli describe shape.insert/format.sizebefore:
after:
Alternative sets of parameters read as
either:/or::A result reads as
Answers with {text}., a remark after the parameters asNote: …. "Acts on…" names only theidoridskey the command takes. A command whose parameters are all optional is run by its bare id.deckcraft-cli commands format.sizebefore: the full registry entry as pretty JSON, about 8 lines per command. In a session with no presentation, every command printed
"enabled": false.after: one line per command; all 226 come to about 16k characters.
How
help.rsholds one entry per subcommand: its usage line, a one-line summary and its own text. The overview,help SUBandSUB --helpare all printed from it, and each subcommand's text stands on its own.describereads the parameters from the command's params doc.parse_paramsreturns each parameter's name, whether it is optional, what the doc says of it, and whether it is an alternative;param_keyslists the keys, and a test requires every params doc to parse.CommandSpec::acts_onin the engine. It combines the command's availability gate with theid/idskeys it actually takes, and a test checks every command against that.shape.move,shape.resize,picture.crop,format.margins,design.slideSize,table.options,table.split).file.export'sformatis marked optional, as it is in the code, andtable.splitlistsrow/col, which it reads.format.colorandfile.recovery.discardare reworded to fit the grammar. The keys don't change.format.*acts on: the selection, notids.docs/mcp.mdanddocs/control-protocol.mdcarry the current usage (describe COMMAND,app --method METHOD [PARAMS]).Test plan
cargo xtask ci: fmt, clippy, tests, assets, layers, wasmrunexample;--help,-handhelp SUBwith its usage and writes no file;run --helpcarries the facts the ids don't;describeoutput is pinned exactly;commandsprints one line per command.parse_paramsspells out each parameter, including alternatives and remarks; every params doc parses; "Acts on…" names only keys the command takes.mainand this branch.Breaking changes
deckcraft-cli commandsprints one line per command instead of JSON. MCP'slist_commandsand the control channel'sengine.commandsstill return JSON.Overlap
#302 (answers) and #304 (templates) also start from
mainand touch some of the same lines: params docs,cmd/mod.rs, the ROADMAP log, the end oftests.rs. Whichever lands second, I'll mergemaininto it. With #302 merged, therunpage can mention itsOK:line.[claude-opus-5-5] on behalf of hoblin