feat(create): guided wizard with use-case and language filters (#1278)

Closes #1236.

**TL;DR** — `apify create` becomes a guided wizard: **use case →
language → best-match template**, plus `apify templates ls` for
discovery. Local scaffold only; the git-sourced flow is #1237 and
`--json`/`--origin` is #1238.

## What changed

- **Wizard** — asks _"What do you want to build?"_ then the language,
then shows one scrollable, fit-ranked template list: exact matches first
(top preselected), a separator, then the closest alternatives.
- **New flags** `-u/--use-case`, `-l/--language`. `-t/--template` stays
authoritative and skips the wizard; `-u`/`-l` are ignored when it's
passed.
- **Language aliases** `js` / `ts` / `py`. No `other` option — every
template has a language.
- **New command** `apify templates ls [--json]`; `--json` emits the full
template objects, including `useCases[]`.
- **Ported** `getTemplateRecommendation` from apify-core, with two CLI
changes: per-template `isExactMatch` and no result limit.

## Flag → manifest mapping

| `--use-case` | manifest tag | | `--language` (+ alias) | `category` |
|---|---|---|---|---|
| `web-scraper` | `WEB_SCRAPING` | | `javascript` / `js` | `javascript`
|
| `ai-agent` | `AI` | | `typescript` / `ts` | `typescript` |
| `data-pipeline` | `INTEGRATION` | | `python` / `py` | `python` |
| `browser-automation` | `AUTOMATION` | | | |

"Any use case" and "Any language" both mean **no filter**
(`ANY_TEMPLATE_USE_CASE` / `ANY_TEMPLATE_LANGUAGE` — symmetric by
design).

## Tests

Unit tests for `getTemplateRecommendation` (tiers, dedup, any-language,
no-exact), `buildTemplateChoiceList` (separator, labels, hint), and the
flag→tag mappings; `create` covers `--template` precedence. `build` /
`lint` / `format` clean, `docs/` regenerated, wizard driven end-to-end
in a terminal.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Edyta <142720610+szaganek@users.noreply.github.com>
Co-authored-by: David Hanuš <david.hanus@apify.com>

Author: 4 people

docs/reference.md

@@ -277,13 +277,20 @@ DESCRIPTION
   directory.
 
 USAGE
-  $ apify create [actorName] [--omit-optional-deps]
-                 [--skip-dependency-install] [--skip-git-init] [-t <value>]
+  $ apify create [actorName]
+                 [-l javascript|js|typescript|ts|python|py]
+                 [--omit-optional-deps] [--skip-dependency-install]
+                 [--skip-git-init] [-t <value>]
+                 [-u web-scraper|ai-agent|data-pipeline|browser-automation]
 
 ARGUMENTS
   actorName  Name of the Actor and its directory.
 
 FLAGS
+  -l, --language=<option>        Filter templates by
+                                 programming language. Ignored when --template is
+                                 provided.
+                                 <options: javascript|js|typescript|ts|python|py>
       --omit-optional-deps       Skip installing optional
                                  dependencies.
       --skip-dependency-install  Skip installing Actor
@@ -295,6 +302,37 @@ FLAGS
                                  it. Visit
                                  https://raw.githubusercontent.com/apify/actor-templates/master/templates/manifest.json
                                  to find available template names.
+  -u, --use-case=<option>        Filter templates by
+                                 use case. Ignored when --template is provided. To
+                                 see the use cases each template supports, run
+                                 "apify templates ls".
+                                 <options:
+                                 web-scraper|ai-agent|data-pipeline|browser-automation>
+```
+
+##### `apify templates`
+
+```sh
+DESCRIPTION
+  Explore the Actor templates used by "apify create".
+
+SUBCOMMANDS
+  templates ls  Prints all available Actor templates, including the
+                use cases and language each one supports.
+```
+
+##### `apify templates ls`
+
+```sh
+DESCRIPTION
+  Prints all available Actor templates, including the use cases and language 
+  each one supports.
+
+USAGE
+  $ apify templates ls [--json]
+
+FLAGS
+      --json  Format the command output as JSON.
 ```
 
 ##### `apify init`

scripts/generate-cli-docs.ts

@@ -21,6 +21,8 @@ const categories: Record<string, CommandsInCategory[]> = {
 	'actor-dev': [
 		//
 		{ command: Commands.create },
+		{ command: Commands.templates },
+		{ command: Commands.templatesLs },
 		{ command: Commands.init },
 		{ command: Commands.run },
 		{ command: Commands.validateSchema },

src/commands/_register.ts

@@ -34,6 +34,7 @@ import { RunsIndexCommand } from './runs/_index.js';
 import { SecretsIndexCommand } from './secrets/_index.js';
 import { TasksIndexCommand } from './task/_index.js';
 import { TelemetryIndexCommand } from './telemetry/_index.js';
+import { TemplatesIndexCommand } from './templates/_index.js';
 import { ValidateSchemaCommand } from './validate-schema.js';
 
 export const apifyCommands = [
@@ -50,6 +51,7 @@ export const apifyCommands = [
 	SecretsIndexCommand,
 	TasksIndexCommand,
 	TelemetryIndexCommand,
+	TemplatesIndexCommand,
 
 	// top-level
 	ApiCommand,

src/commands/create.ts

@@ -30,6 +30,7 @@ import { getInstallCommandSuggestion } from '../lib/hooks/runtimes/utils.js';
 import { ProjectLanguage, useCwdProject } from '../lib/hooks/useCwdProject.js';
 import { createPrefilledInputFileFromInputSchema } from '../lib/input_schema.js';
 import { error, info, simpleLog, success, warning } from '../lib/outputs.js';
+import { LANGUAGE_FLAG_CHOICES, USE_CASE_FLAG_CHOICES } from '../lib/templates/consts.js';
 import {
 	downloadAndUnzip,
 	getJsonFileContent,
@@ -50,13 +51,17 @@ export class CreateCommand extends ApifyCommand<typeof CreateCommand> {
 	static override interactive = true;
 
 	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.';
+		'Prompts for an Actor name, then guides you through what you want to build, a language, and a template when they are not provided. To run non-interactively, pass the name and --template. Use --use-case and --language to narrow the template list.';
 
 	static override examples = [
 		{
-			description: 'Create a new Actor project interactively (prompts for name and template).',
+			description: 'Create a new Actor project interactively (guided name, use case, language, and template prompts).',
 			command: 'apify create',
 		},
+		{
+			description: 'Narrow the guided template list by use case and language.',
+			command: 'apify create my-actor --use-case web-scraper --language python',
+		},
 		{
 			description: 'Create non-interactively with explicit name and template.',
 			command: 'apify create my-actor --template js-crawlee-cheerio',
@@ -75,6 +80,19 @@ export class CreateCommand extends ApifyCommand<typeof CreateCommand> {
 			description: `Template for the Actor. If not provided, the command will prompt for it. Visit ${manifestUrl} to find available template names.`,
 			required: false,
 		}),
+		'use-case': Flags.string({
+			char: 'u',
+			description:
+				'Filter templates by use case. Ignored when --template is provided. To see the use cases each template supports, run "apify templates ls".',
+			choices: USE_CASE_FLAG_CHOICES,
+			required: false,
+		}),
+		language: Flags.string({
+			char: 'l',
+			description: 'Filter templates by programming language. Ignored when --template is provided.',
+			choices: LANGUAGE_FLAG_CHOICES,
+			required: false,
+		}),
 		'skip-dependency-install': Flags.boolean({
 			description: 'Skip installing Actor dependencies.',
 			required: false,
@@ -104,7 +122,7 @@ export class CreateCommand extends ApifyCommand<typeof CreateCommand> {
 
 	async run() {
 		let { actorName } = this.args;
-		const { template: templateName, skipDependencyInstall, skipGitInit } = this.flags;
+		const { template: templateName, useCase, language, skipDependencyInstall, skipGitInit } = this.flags;
 
 		// --template-archive-url is an internal, undocumented flag that's used
 		// for testing of templates that are not yet published in the manifest
@@ -157,7 +175,7 @@ export class CreateCommand extends ApifyCommand<typeof CreateCommand> {
 		};
 
 		if (!templateArchiveUrl) {
-			const templateDefinition = await getTemplateDefinition(templateName, manifestPromise);
+			const templateDefinition = await getTemplateDefinition(templateName, manifestPromise, { useCase, language });
 			({ archiveUrl: templateArchiveUrl, messages } = templateDefinition);
 			this.telemetryData.create.templateId = templateDefinition.id;
 			this.telemetryData.create.templateName = templateDefinition.name;

src/commands/templates/_index.ts

@@ -0,0 +1,16 @@
+import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
+import { TemplatesLsCommand } from './ls.js';
+
+export class TemplatesIndexCommand extends ApifyCommand<typeof TemplatesIndexCommand> {
+	static override name = 'templates' as const;
+
+	static override description = 'Explore the Actor templates used by "apify create".';
+
+	static override group = 'Local Actor Development';
+
+	static override subcommands = [TemplatesLsCommand];
+
+	async run() {
+		this.printHelp();
+	}
+}

src/commands/templates/ls.ts

@@ -0,0 +1,63 @@
+import { fetchManifest } from '@apify/actor-templates';
+
+import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
+import { CompactMode, ResponsiveTable } from '../../lib/commands/responsive-table.js';
+import { info, simpleLog } from '../../lib/outputs.js';
+import { printJsonToStdout } from '../../lib/utils.js';
+
+const table = new ResponsiveTable({
+	allColumns: ['Template', 'Label', 'Language', 'Use cases'],
+	mandatoryColumns: ['Template', 'Language', 'Use cases'],
+});
+
+export class TemplatesLsCommand extends ApifyCommand<typeof TemplatesLsCommand> {
+	static override name = 'ls' as const;
+
+	static override description =
+		'Prints all available Actor templates, including the use cases and language each one supports.';
+
+	static override examples = [
+		{
+			description: 'List all available templates.',
+			command: 'apify templates ls',
+		},
+		{
+			description: 'List templates as JSON (includes the use-case tags for scripting).',
+			command: 'apify templates ls --json',
+		},
+	];
+
+	static override enableJsonFlag = true;
+
+	async run() {
+		const { json } = this.flags;
+
+		const manifest = await fetchManifest().catch((err) => {
+			throw new Error(`Could not fetch template list from server. Cause: ${(err as Error)?.message}`);
+		});
+
+		if (json) {
+			printJsonToStdout(manifest.templates);
+			return;
+		}
+
+		if (manifest.templates.length === 0) {
+			info({ message: 'There are no templates available.', stdout: true });
+			return;
+		}
+
+		for (const template of manifest.templates) {
+			table.pushRow({
+				Template: template.name,
+				Label: template.label,
+				Language: template.category,
+				'Use cases': (template.useCases ?? []).join(', '),
+			});
+		}
+
+		simpleLog({
+			message: table.render(CompactMode.WebLikeCompact),
+			stdout: true,
+		});
+	}
+}