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

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

@@ -21,25 +21,44 @@ export class ActorChargeCommand extends ApifyCommand<typeof ActorChargeCommand>
 
 	static override description = 'Charge for a specific event in the 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 record into 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 = [
 		//

src/commands/actors/call.ts

@@ -32,6 +32,29 @@ export class ActorsCallCommand extends ApifyCommand<typeof ActorsCallCommand> {
 		'Executes Actor remotely using your authenticated account.\n' +
 		'Reads input from local key-value store by default.';
 
+	static override group = 'Apify Console';
+
+	static override examples = [
+		{
+			description: 'Call the Actor defined in the current directory (from .actor/actor.json).',
+			command: 'apify call',
+		},
+		{
+			description: 'Call a specific Actor by its full name.',
+			command: 'apify call apify/hello-world',
+		},
+		{
+			description: 'Call an Actor with inline JSON input.',
+			command: `apify call apify/hello-world --input '{"url":"https://example.com"}'`,
+		},
+		{
+			description: 'Call an Actor with input from a file and print the dataset on success.',
+			command: 'apify call apify/web-scraper --input-file input.json --output-dataset',
+		},
+	];
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#apify-call';
+
 	static override flags = {
 		...SharedRunOnCloudFlags('Actor'),
 		input: Flags.string({

src/commands/actors/info.ts

@@ -46,6 +46,23 @@ export class ActorsInfoCommand extends ApifyCommand<typeof ActorsInfoCommand> {
 
 	static override description = 'Get information about an Actor.';
 
+	static override examples = [
+		{
+			description: 'Print summary information about an Actor.',
+			command: 'apify actors info apify/hello-world',
+		},
+		{
+			description: 'Print the Actor README only.',
+			command: 'apify actors info apify/hello-world --readme',
+		},
+		{
+			description: 'Print the Actor input schema as JSON.',
+			command: 'apify actors info apify/hello-world --input',
+		},
+	];
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#apify-actors-info';
+
 	static override flags = {
 		readme: Flags.boolean({
 			description: 'Return the Actor README.',

src/commands/actors/ls.ts

@@ -99,6 +99,23 @@ export class ActorsLsCommand extends ApifyCommand<typeof ActorsLsCommand> {
 
 	static override description = 'Prints a list of recently executed Actors or Actors you own.';
 
+	static override examples = [
+		{
+			description: 'List Actors you recently interacted with.',
+			command: 'apify actors ls',
+		},
+		{
+			description: 'List Actors you own, newest first.',
+			command: 'apify actors ls --my --desc',
+		},
+		{
+			description: 'List the next page of 50 Actors.',
+			command: 'apify actors ls --limit 50 --offset 50',
+		},
+	];
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#apify-actors-ls';
+
 	static override flags = {
 		my: Flags.boolean({
 			description: 'Whether to list Actors made by the logged in user.',

src/commands/actors/pull.ts

@@ -31,14 +31,33 @@ export class ActorsPullCommand extends ApifyCommand<typeof ActorsPullCommand> {
 		'Download Actor code to current directory. ' +
 		'Clones Git repositories or fetches Actor files based on the source type.';
 
+	static override group = 'Local Actor Development';
+
+	static override examples = [
+		{
+			description: 'Pull the Actor linked to the current directory from the Apify platform.',
+			command: 'apify pull',
+		},
+		{
+			description: 'Pull a specific Actor by its full name into a target directory.',
+			command: 'apify pull apify/hello-world --dir ./hello-world',
+		},
+		{
+			description: 'Pull a specific version of an Actor.',
+			command: 'apify pull apify/hello-world --version 1.2',
+		},
+	];
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#apify-pull';
+
 	static override flags = {
 		version: Flags.string({
 			char: 'v',
-			description: 'Actor version number which will be pulled, e.g. 1.2. Default: the highest version',
+			description: 'Actor version number which will be pulled, e.g. 1.2. Default: the highest version.',
 			required: false,
 		}),
 		dir: Flags.string({
-			description: 'Directory where the Actor should be pulled to',
+			description: 'Directory where the Actor should be pulled to.',
 			required: false,
 		}),
 	};