feat: improve --help output for AI agents and humans#1080
Open
patrikbraborec wants to merge 5 commits intomasterfrom
Open
feat: improve --help output for AI agents and humans#1080patrikbraborec wants to merge 5 commits intomasterfrom
patrikbraborec wants to merge 5 commits intomasterfrom
Conversation
Extends the command framework with examples, docsUrl, interactive, and group metadata, reworks the main help menu with category groups, and adds EXAMPLES + LEARN MORE sections modeled after gh. Also fixes misleading namespace descriptions, clarifies the 'actor' entrypoint's relationship to 'apify actor', supports 'help' as a positional arg equivalent to --help, and normalizes sentence punctuation across all descriptions. Refs #1060 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
patrikbraborec
added
t-dx
Per-command EXAMPLES and the main help menu now prefix example descriptions with "# " (shell-comment style), matching the `gh` CLI convention. Each example becomes a self-contained copy-paste block, which prevents AI agents from mistaking description prose for part of the command. Also updates the main-help `apify create` example to its interactive form (dropping the stray `my-actor` positional) with a comment explaining the flow, so users don't copy an invocation that looks incomplete. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
Author
|
@TC-MO I added you as optional review, if you want to check the help commands. |
Contributor
|
Thank you will check in the afternoon |
l2ysho
requested changes
Apr 15, 2026
Contributor
l2ysho
left a comment
l2ysho
left a comment
There was a problem hiding this comment.
thx @patrikbraborec, i found one possible problem, pls take a look
The previous help-rewrite logic scanned every positional past index 0 for the literal word "help", which hijacked commands whose own args happened to be "help" (e.g. `actor set-value key1 help` or `actor set-value help value1` would show help instead of writing to the key-value store). Only treat a positional as a help trigger when it is an actual subcommand slot: position 1 when the base command has subcommands, and position 2 only when position 1 is a real subcommand and that subcommand takes no positional args of its own. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Implements the findings from the staff review of the help output rework: prefix bare 'actor' example commands with the current entrypoint so they stay copy-pasteable when viewed under 'apify actor', render the interactive note on namespace commands, drop the now-unused mapGroupBy helper, add unit tests for the help renderers, and note the no-op path of the help-positional rewrite under the actor entrypoint. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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
4 participants
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.
Summary
--helpoutput across all CLI commands with structured metadata (descriptions, examples, flags, environment variables) that is useful for both human users and AI agentsinteractiveNote,docsUrl,examples, andaiNotestatic properties to commands for richer help text_BaseCommandRenderer,CommandHelp,CommandWithSubcommands) to support the new structured output format#comments (matches theghCLI convention) in both per-command EXAMPLES and the main help menu, so each example is a self-contained copy-paste blockapify createexample to its interactive form with a#-commented description, instead of the misleadingapify create my-actorinvocationTest plan
yarn lintpassesyarn formatpasses (only untracked.claude/settings.local.jsonfails, not part of the project)yarn buildsucceedsapify <cmd> --helprenders example descriptions as#commentsapify helpmain menu shows the commentedapify createexampleCloses #1060
🤖 Generated with Claude Code