feat: improve --help output for AI agents and humans by patrikbraborec · Pull Request #1080 · apify/apify-cli

patrikbraborec · 2026-04-14T12:25:33Z

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

🤖 Generated with Claude Code

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>

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 · 2026-04-15T08:24:49Z

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

TC-MO · 2026-04-15T08:25:42Z

Thank you will check in the afternoon

l2ysho

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>

l2ysho

lgtm

vladfrangu

Can we get some before and after screenshots please 🙏

vladfrangu · 2026-04-16T17:45:05Z

+
+	static override examples = [
+		{
+			description: 'Log in interactively (opens a browser to complete the flow).',


Technically you pick an option and then fill it in depending on the option you picked

vladfrangu · 2026-04-16T17:45:16Z

+			command: 'apify login --token apify_api_xxxxx',
+		},
+		{
+			description: 'Log in by manually pasting a token instead of opening a browser.',


This will prompt the token, better to remove this example

vladfrangu · 2026-04-16T17:48:05Z


+	static override interactive = true;
+
+	static override interactiveNote = 'Prompts for confirmation before deleting.';


Lets add the same warning of "it cant be skipped" (even tho technically it can with echo "y" | apify datasets rm xxx

vladfrangu · 2026-04-16T17:48:36Z


+	static override interactive = true;
+
+	static override interactiveNote = 'Prompts for confirmation before deleting.';


vladfrangu · 2026-04-16T17:50:15Z


+	static override interactive = true;
+
+	static override interactiveNote = 'Prompts for confirmation before deleting.';


vladfrangu · 2026-04-16T17:52:07Z

+	static override interactiveNote =
+		'Prompts for an Actor name and template if not provided. To run non-interactively, pass the name as a positional argument and --template.';


Maybe we need a non-interactive example too?

vladfrangu · 2026-04-16T17:56:15Z

-/**
- * A "polyfill" for Map.groupBy
- */
-export function mapGroupBy<K, T>(items: Iterable<T>, keySelector: (item: T, index: number) => K): Map<K, T[]> {


Unless it throws errors, dont remove this, as we might want it in the future

patrikbraborec and others added 2 commits April 13, 2026 16:15

fix: resolve lint and format issues in help output changes

56b8add

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

patrikbraborec requested a review from vladfrangu as a code owner April 14, 2026 12:25

github-actions bot assigned patrikbraborec Apr 14, 2026

github-actions bot added this to the 138th sprint - Cash & Community team milestone Apr 14, 2026

github-actions bot added the t-c&c Team covering store and finance matters. label Apr 14, 2026

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 modified the milestones: 138th sprint - Cash & Community team, mile Apr 15, 2026

patrikbraborec requested review from DaveHanns, TC-MO and l2ysho April 15, 2026 08:24

l2ysho requested changes Apr 15, 2026

View reviewed changes

Comment thread src/entrypoints/_shared.ts

patrikbraborec and others added 2 commits April 15, 2026 14:20

l2ysho approved these changes Apr 15, 2026

View reviewed changes

vladfrangu requested changes Apr 16, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

feat: improve --help output for AI agents and humans#1080
patrikbraborec wants to merge 5 commits intomasterfrom
fix/help-output-ai-agents

patrikbraborec commented Apr 14, 2026 •

edited

Loading

Uh oh!

patrikbraborec commented Apr 15, 2026

Uh oh!

TC-MO commented Apr 15, 2026

Uh oh!

l2ysho left a comment

Uh oh!

Uh oh!

l2ysho left a comment

Uh oh!

vladfrangu left a comment

Uh oh!

vladfrangu Apr 16, 2026

Uh oh!

vladfrangu Apr 16, 2026

Uh oh!

vladfrangu Apr 16, 2026

Uh oh!

vladfrangu Apr 16, 2026

Uh oh!

vladfrangu Apr 16, 2026

Uh oh!

vladfrangu Apr 16, 2026

Uh oh!

vladfrangu Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		static override interactive = true;

		static override interactiveNote = 'Prompts for confirmation before deleting.';

		static override interactiveNote =
		'Prompts for an Actor name and template if not provided. To run non-interactively, pass the name as a positional argument and --template.';

Conversation

patrikbraborec commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

patrikbraborec commented Apr 15, 2026

Uh oh!

TC-MO commented Apr 15, 2026

Uh oh!

l2ysho left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

l2ysho left a comment

Choose a reason for hiding this comment

Uh oh!

vladfrangu left a comment

Choose a reason for hiding this comment

Uh oh!

vladfrangu Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

vladfrangu Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

vladfrangu Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

vladfrangu Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

vladfrangu Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

vladfrangu Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

vladfrangu Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

patrikbraborec commented Apr 14, 2026 •

edited

Loading