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

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

Closes #1060

## Help command before

<img width="897" height="653" alt="image"
src="https://github.com/user-attachments/assets/b231dfc3-fd85-4b5a-bc82-aa5dfa75b4a5"
/>

## Help command in this implementation

<img width="897" height="1035" alt="image"
src="https://github.com/user-attachments/assets/2b84f3c3-a9e2-4221-805a-08663d300bc9"
/>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Author: 3 people

src/commands/actor/_index.ts

@@ -11,7 +11,13 @@ import { ActorSetValueCommand } from './set-value.js';
 export class ActorIndexCommand extends ApifyCommand<typeof ActorIndexCommand> {
 	static override name = 'actor' as const;
 
-	static override description = 'Manages runtime data operations inside of a running Actor.';
+	static override description =
+		`Runtime data operations intended to be called from inside a running Actor: read input, push data, get/set records in the default key-value store, charge pay-per-event, generate schema types.\n\n` +
+		`For platform-level management (deploy, list, call Actors), see 'apify actors' (plural).`;
+
+	static override group = 'Apify Console';
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#apify-actor';
 
 	static override subcommands = [
 		//

src/commands/actor/calculate-memory.ts

@@ -31,6 +31,21 @@ export class ActorCalculateMemoryCommand extends ApifyCommand<typeof ActorCalcul
 	static override description =
 		`Calculates the Actor’s dynamic memory usage based on a memory expression from actor.json, input data, and run options.`;
 
+	static override group = 'Actor Runtime';
+
+	static override examples = [
+		{
+			description: 'Calculate memory using the expression and input defaults from actor.json.',
+			command: 'actor calculate-memory',
+		},
+		{
+			description: 'Override the memory expression and input file.',
+			command: 'actor calculate-memory --defaultMemoryMbytes "input.length * 128" --input ./my-input.json',
+		},
+	];
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#actor-calculate-memory';
+
 	/**
 	 * Additional run options exist (e.g., memoryMbytes, disksMbytes, etc.),
 	 * but we intentionally omit them here. These options are rarely needed and

src/commands/actor/charge.ts

@@ -19,27 +19,46 @@ import { getLoggedClient } from '../../lib/utils.js';
 export class ActorChargeCommand extends ApifyCommand<typeof ActorChargeCommand> {
 	static override name = 'charge' as const;
 
-	static override description = 'Charge for a specific event in the pay-per-event Actor run.';
+	static override description = 'Charge for a specific event in a pay-per-event Actor run.';
+
+	static override group = 'Actor Runtime';
+
+	static override examples = [
+		{
+			description: 'Charge one event of the given type.',
+			command: 'actor charge result-item',
+		},
+		{
+			description: 'Charge 5 events with an idempotency key.',
+			command: 'actor charge result-item --count 5 --idempotency-key req-123',
+		},
+		{
+			description: 'Test locally without actually charging.',
+			command: 'actor charge result-item --test-pay-per-event',
+		},
+	];
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#actor-charge';
 
 	static override args = {
 		eventName: Args.string({
-			description: 'Name of the event to charge for',
+			description: 'Name of the event to charge for.',
 			required: true,
 		}),
 	};
 
 	static override flags = {
 		'count': Flags.integer({
-			description: 'Number of events to charge',
+			description: 'Number of events to charge.',
 			required: false,
 			default: 1,
 		}),
 		'idempotency-key': Flags.string({
-			description: 'Idempotency key for the charge request',
+			description: 'Idempotency key for the charge request.',
 			required: false,
 		}),
 		'test-pay-per-event': Flags.boolean({
-			description: 'Test pay-per-event charging without actually charging',
+			description: 'Test pay-per-event charging without actually charging.',
 			required: false,
 			default: false,
 		}),

src/commands/actor/generate-schema-types.ts

@@ -56,6 +56,25 @@ Reads the input schema from one of these locations (in priority order):
 
 Optionally specify custom schema path to use.`;
 
+	static override group = 'Actor Runtime';
+
+	static override examples = [
+		{
+			description: 'Generate TypeScript types from the input schema into the default output directory.',
+			command: 'actor generate-schema-types',
+		},
+		{
+			description: 'Generate types from a custom schema path.',
+			command: 'actor generate-schema-types ./schemas/my-input.json',
+		},
+		{
+			description: 'Mark all generated properties as optional.',
+			command: 'actor generate-schema-types --all-optional',
+		},
+	];
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#actor-generate-schema-types';
+
 	static override flags = {
 		output: Flags.string({
 			char: 'o',

src/commands/actor/get-input.ts

@@ -7,6 +7,17 @@ export class ActorGetInputCommand extends ApifyCommand<typeof ActorGetInputComma
 	static override description =
 		'Gets the Actor input value from the default key-value store associated with the Actor run.';
 
+	static override group = 'Actor Runtime';
+
+	static override examples = [
+		{
+			description: 'Print the current Actor input to stdout.',
+			command: 'actor get-input',
+		},
+	];
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#actor-get-input';
+
 	async run() {
 		await outputInputFromDefaultStore();
 	}

src/commands/actor/get-public-url.ts

@@ -13,10 +13,21 @@ export class ActorGetPublicUrlCommand extends ApifyCommand<typeof ActorGetPublic
 
 	static override description = 'Get an HTTP URL that allows public access to a key-value store item.';
 
+	static override group = 'Actor Runtime';
+
+	static override examples = [
+		{
+			description: 'Get a public URL for the record stored under the given key.',
+			command: 'actor get-public-url OUTPUT',
+		},
+	];
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#actor-get-public-url';
+
 	static override args = {
 		key: Args.string({
 			required: true,
-			description: 'Key of the record in key-value store',
+			description: 'Key of the record in the key-value store.',
 		}),
 	};
 

src/commands/actor/get-value.ts

@@ -7,10 +7,21 @@ export class ActorGetValueCommand extends ApifyCommand<typeof ActorGetValueComma
 
 	static override description = 'Gets a value from the default key-value store associated with the Actor run.';
 
+	static override group = 'Actor Runtime';
+
+	static override examples = [
+		{
+			description: 'Read the record stored under the key "INPUT".',
+			command: 'actor get-value INPUT',
+		},
+	];
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#actor-get-value';
+
 	static override args = {
 		key: Args.string({
 			required: true,
-			description: 'Key of the record in key-value store',
+			description: 'Key of the record in the key-value store.',
 		}),
 	};
 

src/commands/actor/push-data.ts

@@ -7,13 +7,22 @@ import { error } from '../../lib/outputs.js';
 export class ActorPushDataCommand extends ApifyCommand<typeof ActorPushDataCommand> {
 	static override name = 'push-data' as const;
 
-	static override description =
-		"Saves data to Actor's run default dataset.\n\n" +
-		'Accept input as:\n' +
-		'  - JSON argument:\n' +
-		'  $ apify actor push-data {"key": "value"}\n' +
-		'  - Piped stdin:\n' +
-		'  $ cat ./test.json | apify actor push-data';
+	static override description = "Saves data to Actor's run default dataset.";
+
+	static override group = 'Actor Runtime';
+
+	static override examples = [
+		{
+			description: 'Push a single item as an inline JSON argument.',
+			command: `actor push-data '{"key":"value"}'`,
+		},
+		{
+			description: 'Push an array of items by piping from stdin.',
+			command: 'cat ./items.json | actor push-data',
+		},
+	];
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#actor-push-data';
 
 	static override args = {
 		item: Args.string({

src/commands/actor/set-value.ts

@@ -7,12 +7,26 @@ export class ActorSetValueCommand extends ApifyCommand<typeof ActorSetValueComma
 	static override name = 'set-value' as const;
 
 	static override description =
-		'Sets or removes record into the default key-value store associated with the Actor run.\n\n' +
-		'It is possible to pass data using argument or stdin.\n\n' +
-		'Passing data using argument:\n' +
-		'$ apify actor set-value KEY my-value\n\n' +
-		'Passing data using stdin with pipe:\n' +
-		'$ cat ./my-text-file.txt | apify actor set-value KEY --contentType text/plain';
+		'Sets or removes a record in the default key-value store associated with the Actor run.';
+
+	static override group = 'Actor Runtime';
+
+	static override examples = [
+		{
+			description: 'Store a JSON value under the key "OUTPUT".',
+			command: `actor set-value OUTPUT '{"status":"done"}'`,
+		},
+		{
+			description: 'Store a file as a text record.',
+			command: 'cat ./report.txt | actor set-value REPORT --contentType text/plain',
+		},
+		{
+			description: 'Delete the record stored under the given key.',
+			command: 'actor set-value OUTPUT',
+		},
+	];
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#actor-set-value';
 
 	static override args = {
 		key: Args.string({

src/commands/actors/_index.ts

@@ -12,7 +12,13 @@ import { ActorsStartCommand } from './start.js';
 export class ActorsIndexCommand extends ApifyCommand<typeof ActorsIndexCommand> {
 	static override name = 'actors' as const;
 
-	static override description = 'Manages Actor creation, deployment, and execution on the Apify platform.';
+	static override description =
+		`Search, list, deploy, and call Actors on the Apify platform.\n` +
+		`For runtime operations inside a running Actor (push-data, get-input, set-value...), see 'apify actor' (singular).`;
+
+	static override group = 'Apify Console';
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#apify-actors';
 
 	static override subcommands = [
 		//