Skip to content

feat: improve --help output for AI agents and humans#1080

Merged
patrikbraborec merged 10 commits intomasterfrom
fix/help-output-ai-agents
Apr 20, 2026
Merged

feat: improve --help output for AI agents and humans#1080
patrikbraborec merged 10 commits intomasterfrom
fix/help-output-ai-agents

Conversation

@patrikbraborec
Copy link
Copy Markdown
Contributor

@patrikbraborec patrikbraborec commented Apr 14, 2026 •
edited
Loading

Summary

  • Enhances --help output across all CLI commands with structured metadata (descriptions, examples, flags, environment variables) that is useful for both human users and AI agents
  • Adds interactiveNote, docsUrl, examples, and aiNote static properties to commands for richer help text
  • Refactors the help rendering system (_BaseCommandRenderer, CommandHelp, CommandWithSubcommands) to support the new structured output format
  • Renders example descriptions as shell-style # comments (matches the gh CLI convention) in both per-command EXAMPLES and the main help menu, so each example is a self-contained copy-paste block
  • Updates the main-help apify create example to its interactive form with a #-commented description, instead of the misleading apify create my-actor invocation
  • Fixes lint and format issues (object destructuring, line length)

Test plan

  • yarn lint passes
  • yarn format passes (only untracked .claude/settings.local.json fails, not part of the project)
  • yarn build succeeds
  • Verified apify <cmd> --help renders example descriptions as # comments
  • Verified apify help main menu shows the commented apify create example

Closes #1060

Help command before

image

Help command in this implementation

image

patrikbraborec and others added 2 commits April 13, 2026 16:15
@patrikbraborec @claude
feat: improve --help output for AI agents and humans
d01eb4b 
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>
@patrikbraborec @claude
fix: resolve lint and format issues in help output changes
56b8add 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@github-actions github-actions Bot added the t-c&c Team covering store and finance matters. label Apr 14, 2026
@patrikbraborec patrikbraborec added t-dx Issues owned by the DX team. and removed t-c&c Team covering store and finance matters. labels Apr 14, 2026
@patrikbraborec @claude
feat: render help examples as shell-style # comments
8762e3b 
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>
@patrikbraborec
Copy link
Copy Markdown
Contributor Author

patrikbraborec commented Apr 15, 2026

@TC-MO I added you as optional review, if you want to check the help commands.

@TC-MO
Copy link
Copy Markdown
Contributor

TC-MO commented Apr 15, 2026

Thank you will check in the afternoon

l2ysho
l2ysho requested changes Apr 15, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@l2ysho l2ysho left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thx @patrikbraborec, i found one possible problem, pls take a look

Comment thread src/entrypoints/_shared.ts
patrikbraborec and others added 2 commits April 15, 2026 14:20
@patrikbraborec @claude
fix: prevent help from hijacking commands with positional args
7807c2c 
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>
@patrikbraborec @claude
refactor: address staff review for help output improvements
21c4ff7 
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>
l2ysho
l2ysho approved these changes Apr 15, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@l2ysho l2ysho left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

vladfrangu
vladfrangu requested changes Apr 16, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@vladfrangu vladfrangu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we get some before and after screenshots please 🙏

Comment thread src/commands/auth/login.ts Outdated
Comment thread src/commands/auth/login.ts Outdated
Comment thread src/commands/datasets/rm.ts Outdated
Comment thread src/commands/key-value-stores/rm.ts Outdated
Comment thread src/commands/runs/rm.ts Outdated
Comment thread src/commands/create.ts
Comment thread src/lib/utils.ts
@patrikbraborec @claude
refactor: address PR feedback on help output changes
9fe0a18 
Clarify that 'apify login' prompts for a method before completing the
flow, drop the redundant --method manual example (still interactive),
extend the delete-command interactive notes to warn that the
confirmation cannot be bypassed and deletion is irreversible, and
restore the mapGroupBy polyfill helper for potential future use.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
TC-MO
TC-MO requested changes Apr 20, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@TC-MO TC-MO left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Grammar fixes: missing articles, wrong prepositions, subject-verb disagreement
  • Tighter phrasing: trimmed wordiness on some descriptions
  • … → ...: no benefit from the Unicode ellipsis in CLI terminal output
  • Trailing periods: 9 flag/arg descriptions in files this PR already touches were missing them, added for consistency

Tech debt for follow-up: the new namespace descriptions use imperative voice ("Manage", "Log in", "Run") while existing descriptions use declarative ("Creates", "Prints", "Gets").

Both are fine individually, but mixed in the same --help menu it looks unintentional. Worth a pass to normalize everything to imperative (the gh/docker/kubectl convention), doesn't need to block this PR but should be done relatively soon.

Comment thread src/commands/actors/_index.ts Outdated
Comment thread src/commands/actor/set-value.ts Outdated
Comment thread src/commands/datasets/rename.ts Outdated
Comment thread src/commands/actor/charge.ts Outdated
Comment thread src/commands/auth/_index.ts Outdated
Comment thread src/commands/key-value-stores/rename.ts Outdated
Comment thread src/commands/key-value-stores/rename.ts Outdated
Comment thread src/commands/key-value-stores/rename.ts Outdated
Comment thread src/commands/key-value-stores/rm.ts Outdated
Comment thread src/commands/key-value-stores/create.ts Outdated
patrikbraborec and others added 3 commits April 20, 2026 14:31
@patrikbraborec @TC-MO
Apply suggestions from code review
a97d097 
Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>
@patrikbraborec @claude
style: apply formatter to index command descriptions
a1ec3f9 
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@patrikbraborec @claude
style: replace Unicode ellipsis with three periods in actors description
1e192c3 
Addresses PR feedback: no benefit from the Unicode ellipsis in CLI terminal output.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@patrikbraborec patrikbraborec mentioned this pull request Apr 20, 2026
Open
@patrikbraborec
Copy link
Copy Markdown
Contributor Author

patrikbraborec commented Apr 20, 2026

Thanks @TC-MO, created ticket for follow up: #1096. Other issues were fixed.

@patrikbraborec patrikbraborec merged commit e9be7ee into master Apr 20, 2026
23 checks passed
@patrikbraborec patrikbraborec deleted the fix/help-output-ai-agents branch April 20, 2026 14:39
patrikbraborec added a commit that referenced this pull request Apr 22, 2026
@patrikbraborec @claude
feat: add EXAMPLES block and docsUrl to apify api
748c0b5 
Moves the inline example blocks out of the description and into the
framework's `examples` field (added in #1080) so they render as the
standard shell-comment EXAMPLES block, matching every other command.
Also wires up `docsUrl` to surface the API reference in LEARN MORE.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@l2ysho l2ysho l2ysho approved these changes

@vladfrangu vladfrangu vladfrangu approved these changes

@TC-MO TC-MO TC-MO approved these changes

@DaveHanns DaveHanns Awaiting requested review from DaveHanns

Assignees

@patrikbraborec patrikbraborec

Labels

t-dx Issues owned by the DX team.

Projects

None yet

Milestone

Apify CLI - improvements

Development

Successfully merging this pull request may close these issues.

Fix --help for AI agents & humans

6 participants

@patrikbraborec @TC-MO @l2ysho @vladfrangu @drobnikj @apify-service-account