From 4d0d4c4d0d9ddfb121aeb9740e1d19ef03bf2b43 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Richard=20Sol=C3=A1r?= <solar.richard@gmail.com>
Date: Thu, 16 Jul 2026 12:08:24 +0200
Subject: [PATCH 1/2] feat(create): guided wizard with use-case and language
 filters

Reshape `apify create` into a guided wizard: prompt for what the user
wants to build (use case) and the language, then present a single
fit-ranked template list (exact matches first, top preselected, a
non-selectable separator, then the closest alternatives).

- Add `-u/--use-case` and `-l/--language` filter flags; `-t/--template`
  stays authoritative and bypasses the wizard.
- Add `apify templates ls [--json]`, exposing each template's
  useCases[] so agents can discover the enum values.
- Port apify-core's getTemplateRecommendation tier algorithm, with a
  per-template isExactMatch flag (no aggregate) and no result limit;
  a skipped use case and "any language" both mean "no filter".

Refs #1236

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/reference.md                             |  39 +++-
 scripts/generate-cli-docs.ts                  |   2 +
 src/commands/_register.ts                     |   2 +
 src/commands/create.ts                        |  18 +-
 src/commands/templates/_index.ts              |  16 ++
 src/commands/templates/ls.ts                  |  63 +++++++
 src/lib/create-utils.ts                       | 133 +++++++-------
 src/lib/templates/consts.ts                   | 102 +++++++++++
 .../templates/getTemplateRecommendation.ts    |  78 ++++++++
 src/lib/templates/templateChoices.ts          |  71 ++++++++
 .../lib/getTemplateRecommendation.test.ts     | 172 ++++++++++++++++++
 test/local/lib/templateChoices.test.ts        |  92 ++++++++++
 12 files changed, 724 insertions(+), 64 deletions(-)
 create mode 100644 src/commands/templates/_index.ts
 create mode 100644 src/commands/templates/ls.ts
 create mode 100644 src/lib/templates/consts.ts
 create mode 100644 src/lib/templates/getTemplateRecommendation.ts
 create mode 100644 src/lib/templates/templateChoices.ts
 create mode 100644 test/local/lib/getTemplateRecommendation.test.ts
 create mode 100644 test/local/lib/templateChoices.test.ts

diff --git a/docs/reference.md b/docs/reference.md
index 09af9be11..33c75780f 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -277,13 +277,19 @@ DESCRIPTION
   directory.
 
 USAGE
-  $ apify create [actorName] [--omit-optional-deps]
+  $ apify create [actorName]
+                 [-l javascript|typescript|python|other] [--omit-optional-deps]
                  [--skip-dependency-install] [--skip-git-init] [-t <value>]
+                 [-u web-scraping|ai-agent|api-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|typescript|python|other>
       --omit-optional-deps       Skip installing optional
                                  dependencies.
       --skip-dependency-install  Skip installing Actor
@@ -295,6 +301,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
+                                 what you want to build. Ignored when --template is
+                                 provided. Run "apify templates ls" to see the use
+                                 cases each template supports.
+                                 <options:
+                                 web-scraping|ai-agent|api-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`
diff --git a/scripts/generate-cli-docs.ts b/scripts/generate-cli-docs.ts
index a45eb8555..8f1335bd6 100644
--- a/scripts/generate-cli-docs.ts
+++ b/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 },
diff --git a/src/commands/_register.ts b/src/commands/_register.ts
index 7f8901543..b1cce10ce 100644
--- a/src/commands/_register.ts
+++ b/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,
diff --git a/src/commands/create.ts b/src/commands/create.ts
index f551d4dab..1fc1cf970 100644
--- a/src/commands/create.ts
+++ b/src/commands/create.ts
@@ -29,6 +29,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,
@@ -74,6 +75,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 what you want to build. Ignored when --template is provided. Run "apify templates ls" to see the use cases each template supports.',
+			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,
@@ -103,7 +117,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
@@ -156,7 +170,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;
diff --git a/src/commands/templates/_index.ts b/src/commands/templates/_index.ts
new file mode 100644
index 000000000..c00d98ace
--- /dev/null
+++ b/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();
+	}
+}
diff --git a/src/commands/templates/ls.ts b/src/commands/templates/ls.ts
new file mode 100644
index 000000000..ec30eafa5
--- /dev/null
+++ b/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,
+		});
+	}
+}
diff --git a/src/lib/create-utils.ts b/src/lib/create-utils.ts
index f38fbc363..6d48e45d4 100644
--- a/src/lib/create-utils.ts
+++ b/src/lib/create-utils.ts
@@ -8,10 +8,17 @@ import type { Manifest, Template } from '@apify/actor-templates';
 import type { ChoicesType } from './hooks/user-confirmations/useSelectFromList.js';
 import { useSelectFromList } from './hooks/user-confirmations/useSelectFromList.js';
 import { useUserInput } from './hooks/user-confirmations/useUserInput.js';
-import { warning } from './outputs.js';
+import { info, warning } from './outputs.js';
+import { ANY_TEMPLATE_LANGUAGE, LANGUAGE_OPTIONS, USE_CASE_OPTIONS, useCaseFlagToId } from './templates/consts.js';
+import { getTemplateRecommendation } from './templates/getTemplateRecommendation.js';
+import { buildTemplateChoiceList, NON_EXACT_SEPARATOR_LABEL } from './templates/templateChoices.js';
 import { validateActorName } from './utils.js';
 
-const PROGRAMMING_LANGUAGES = ['JavaScript', 'TypeScript', 'Python'];
+/** Filters coming from the `--use-case` / `--language` flags. `undefined` means "not provided". */
+export interface TemplateFilters {
+	useCase?: string;
+	language?: string;
+}
 
 export async function ensureValidActorName(maybeActorName?: string) {
 	if (maybeActorName) {
@@ -22,10 +29,10 @@ export async function ensureValidActorName(maybeActorName?: string) {
 	return promptActorName();
 }
 
-// TODO: this isn't even used anymore
 export async function getTemplateDefinition(
 	maybeTemplateName: string | undefined,
 	manifestPromise: Promise<Manifest | Error>,
+	filters: TemplateFilters = {},
 ) {
 	const manifest = await manifestPromise;
 	// If the fetch failed earlier, the resolve value of
@@ -40,10 +47,9 @@ export async function getTemplateDefinition(
 		return templateDefinition;
 	}
 
-	return executePrompts(manifest);
+	return executePrompts(manifest, filters);
 }
 
-// TODO: this isn't even used anymore
 /**
  * Fetch local readme suffix from the manifest and append it to the readme.
  */
@@ -96,22 +102,15 @@ export function formatCreateSuccessMessage(params: {
 }
 
 /**
- * Inquirer does not have a native way to "go back" between prompts.
+ * Guided wizard: ask what the user wants to build and in which language (unless supplied via
+ * flags), then present the best-matching templates ordered by fit.
  */
-async function executePrompts(manifest: Manifest) {
-	const programmingLanguage = await promptProgrammingLanguage();
-
-	while (true) {
-		const templateDefinition = await promptTemplateDefinition(manifest, programmingLanguage);
-		if (templateDefinition) {
-			const shouldInstall = await promptTemplateInstallation();
-			if (shouldInstall) {
-				return templateDefinition;
-			}
-		} else {
-			return executePrompts(manifest);
-		}
-	}
+async function executePrompts(manifest: Manifest, filters: TemplateFilters) {
+	const useCaseId = filters.useCase ? useCaseFlagToId(filters.useCase) : await promptUseCase();
+	// A provided `--language` value is already a manifest `category` (or the `other` marker).
+	const languageId = filters.language ?? (await promptLanguage());
+
+	return promptTemplate(manifest, useCaseId, languageId);
 }
 
 async function promptActorName() {
@@ -130,62 +129,74 @@ async function promptActorName() {
 	return answer;
 }
 
-async function promptProgrammingLanguage() {
-	const language = await useSelectFromList<string>({
-		message: 'Choose the programming language of your new Actor:',
-		choices: PROGRAMMING_LANGUAGES,
+async function promptUseCase(): Promise<string | undefined> {
+	const choices: ChoicesType<string | null> = [
+		...USE_CASE_OPTIONS.map((option) => ({ name: option.label, value: option.id })),
+		new Separator(),
+		{ name: 'Skip (show all)', value: null },
+	];
+
+	const useCaseId = await useSelectFromList<string | null>({
+		message: 'What do you want to build?',
+		choices,
+		default: USE_CASE_OPTIONS[0].id,
 		loop: false,
-		default: PROGRAMMING_LANGUAGES[0],
 	});
 
-	return language;
+	// `null` is the "Skip (show all)" choice — the algorithm treats a missing use case as no filter.
+	return useCaseId ?? undefined;
 }
 
-async function promptTemplateDefinition(manifest: Manifest, programmingLanguage: string): Promise<Template | false> {
-	const choices: ChoicesType<Template | false> = [
-		...manifest.templates
-			.filter((t) => {
-				return t.category.toLowerCase() === programmingLanguage.toLowerCase();
-			})
-			.map((t) => {
-				return {
-					name: t.label,
-					value: t,
-				};
-			}),
-
+async function promptLanguage(): Promise<string> {
+	const choices: ChoicesType<string> = [
+		...LANGUAGE_OPTIONS.map((option) => ({ name: option.label, value: option.id })),
 		new Separator(),
-
-		{
-			name: 'Go back',
-			value: false,
-		},
+		{ name: 'Any language', value: ANY_TEMPLATE_LANGUAGE },
 	];
 
-	const templateDefinition = await useSelectFromList({
-		message: 'Choose a template for your new Actor. You can check more information at https://apify.com/templates.',
-		default: choices[0],
+	return useSelectFromList<string>({
+		message: 'Choose the programming language of your new Actor:',
 		choices,
+		default: LANGUAGE_OPTIONS[0].id,
 		loop: false,
-		pageSize: 8,
 	});
-
-	return templateDefinition;
 }
 
-async function promptTemplateInstallation() {
-	const choices: ChoicesType<boolean> = [
-		{ name: `Install dependencies`, value: true },
-		new Separator(),
-		{ name: 'Go back', value: false },
-	];
+/**
+ * Renders one scrollable list ordered by fit: exact matches first (top one preselected), then a
+ * non-selectable separator, then the closest alternatives. When nothing matches exactly, an info
+ * line explains that the closest alternatives are shown instead.
+ */
+async function promptTemplate(
+	manifest: Manifest,
+	useCaseId: string | undefined,
+	languageId: string,
+): Promise<Template> {
+	const recommendations = getTemplateRecommendation(manifest.templates, useCaseId, languageId);
+	const { rows, separatorIndex, noExactMatchHint } = buildTemplateChoiceList(recommendations, useCaseId, languageId);
+
+	if (rows.length === 0) {
+		throw new Error('No Actor templates are available right now. Please try again later.');
+	}
+
+	const choices: NonNullable<ChoicesType<Template>>[number][] = [];
+	rows.forEach((row, index) => {
+		if (index === separatorIndex) {
+			choices.push(new Separator(NON_EXACT_SEPARATOR_LABEL));
+		}
 
-	const answer = await useSelectFromList<boolean>({
-		message: 'Almost done! Last step is to install dependencies.',
-		default: choices[0],
+		choices.push({ name: row.label, value: row.template });
+	});
+
+	if (noExactMatchHint) {
+		info({ message: noExactMatchHint, stdout: false });
+	}
+
+	return useSelectFromList<Template>({
+		message: 'Choose a template for your new Actor. More info at https://apify.com/templates',
 		choices,
+		default: rows[0].template,
 		loop: false,
+		pageSize: 8,
 	});
-
-	return answer;
 }
diff --git a/src/lib/templates/consts.ts b/src/lib/templates/consts.ts
new file mode 100644
index 000000000..92341e172
--- /dev/null
+++ b/src/lib/templates/consts.ts
@@ -0,0 +1,102 @@
+/**
+ * Template taxonomy constants, ported from apify-core `src/packages/consts/src/templates.ts`.
+ *
+ * These are internal to apify-core and are NOT exported by the `@apify/actor-templates`
+ * package, so they are copied here. They must stay in sync with the manifest served from
+ * https://github.com/apify/actor-templates (the `category` and `useCases` fields).
+ */
+
+/** Use-case ids as they appear in the manifest's `useCases[]` (SCREAMING_SNAKE). */
+export const TEMPLATE_USE_CASES = {
+	/** Entry-level scaffold for a user's first Actor. Not exposed as a wizard option; used by the fallback tiers. */
+	STARTER: 'STARTER',
+	WEB_SCRAPING: 'WEB_SCRAPING',
+	INTEGRATION: 'INTEGRATION',
+	AUTOMATION: 'AUTOMATION',
+	AI: 'AI',
+} as const;
+
+/** Language ids, equal to the manifest's `category` field (lowercase). */
+export const TEMPLATE_LANGUAGES = {
+	JAVASCRIPT: 'javascript',
+	TYPESCRIPT: 'typescript',
+	PYTHON: 'python',
+} as const;
+
+/** Marker value representing "no specific language". */
+export const ANY_TEMPLATE_LANGUAGE = 'any-language';
+
+export const QUICK_START_TEMPLATE_IDS: Record<string, string | undefined> = {
+	[TEMPLATE_LANGUAGES.TYPESCRIPT]: 'ts-crawlee-cheerio',
+	[TEMPLATE_LANGUAGES.JAVASCRIPT]: 'js-crawlee-cheerio',
+	[TEMPLATE_LANGUAGES.PYTHON]: 'python-crawlee-beautifulsoup',
+};
+
+export const EMPTY_TEMPLATE_IDS: Record<string, string | undefined> = {
+	[TEMPLATE_LANGUAGES.TYPESCRIPT]: 'ts-empty',
+	[TEMPLATE_LANGUAGES.JAVASCRIPT]: 'js-empty',
+	[TEMPLATE_LANGUAGES.PYTHON]: 'python-empty',
+};
+
+export interface UseCaseOption {
+	/** kebab-case value accepted by the `--use-case` flag. */
+	flag: string;
+	/** Manifest id this maps to (value in `useCases[]`). */
+	id: string;
+	/** Human-readable label shown in the interactive prompt. */
+	label: string;
+}
+
+/**
+ * The four use cases exposed by the wizard, in prompt order. `STARTER` is intentionally
+ * omitted — it only tags quick-start/empty templates so they surface via the fallback tiers.
+ */
+export const USE_CASE_OPTIONS: UseCaseOption[] = [
+	{ flag: 'web-scraping', id: TEMPLATE_USE_CASES.WEB_SCRAPING, label: 'Web scraping' },
+	{ flag: 'ai-agent', id: TEMPLATE_USE_CASES.AI, label: 'AI agent' },
+	{ flag: 'api-pipeline', id: TEMPLATE_USE_CASES.INTEGRATION, label: 'API & data pipeline' },
+	{ flag: 'browser-automation', id: TEMPLATE_USE_CASES.AUTOMATION, label: 'Browser automation' },
+];
+
+export interface LanguageOption {
+	/** Manifest `category`, which is also the value accepted by the `--language` flag. */
+	id: string;
+	/** Human-readable label shown in the interactive prompt. */
+	label: string;
+}
+
+/** The three concrete languages, in prompt order. */
+export const LANGUAGE_OPTIONS: LanguageOption[] = [
+	{ id: TEMPLATE_LANGUAGES.JAVASCRIPT, label: 'JavaScript' },
+	{ id: TEMPLATE_LANGUAGES.TYPESCRIPT, label: 'TypeScript' },
+	{ id: TEMPLATE_LANGUAGES.PYTHON, label: 'Python' },
+];
+
+/**
+ * BYO-Docker escape hatch. Kept as a valid `--language` value even though no manifest
+ * template matches it today; the recommendation falls through to showing all templates.
+ */
+export const OTHER_LANGUAGE = 'other';
+
+/** Every accepted `--language` flag value. */
+export const LANGUAGE_FLAG_CHOICES: string[] = [...LANGUAGE_OPTIONS.map((option) => option.id), OTHER_LANGUAGE];
+
+/** Every accepted `--use-case` flag value. */
+export const USE_CASE_FLAG_CHOICES: string[] = USE_CASE_OPTIONS.map((option) => option.flag);
+
+/** Maps a `--use-case` flag value to its manifest id, or `undefined` when unknown. */
+export function useCaseFlagToId(flag: string): string | undefined {
+	return USE_CASE_OPTIONS.find((option) => option.flag === flag)?.id;
+}
+
+/** Human-readable label for a use-case id (used in the "no exact match" hint). */
+export function useCaseLabel(id: string): string {
+	return USE_CASE_OPTIONS.find((option) => option.id === id)?.label ?? id;
+}
+
+/** Human-readable label for a language id (used in the "no exact match" hint). */
+export function languageLabel(id: string): string {
+	if (id === ANY_TEMPLATE_LANGUAGE) return 'any language';
+	if (id === OTHER_LANGUAGE) return 'other';
+	return LANGUAGE_OPTIONS.find((option) => option.id === id)?.label ?? id;
+}
diff --git a/src/lib/templates/getTemplateRecommendation.ts b/src/lib/templates/getTemplateRecommendation.ts
new file mode 100644
index 000000000..cb0d30ea9
--- /dev/null
+++ b/src/lib/templates/getTemplateRecommendation.ts
@@ -0,0 +1,78 @@
+import type { Template } from '@apify/actor-templates';
+
+import { ANY_TEMPLATE_LANGUAGE, EMPTY_TEMPLATE_IDS, QUICK_START_TEMPLATE_IDS } from './consts.js';
+
+export interface TemplateRecommendation {
+	template: Template;
+	/** True when this template matches every active filter (language and/or use case). */
+	isExactMatch: boolean;
+}
+
+/**
+ * Ports apify-core's `getTemplateRecommendation`
+ * (`src/console/frontend/src/ui/actors/actor_new_wizard/get_template_recommendation.ts`),
+ * with two CLI-specific changes:
+ *
+ * - The return shape is a flat, priority-ordered `Array<{ template, isExactMatch }>` — a
+ *   per-template flag rather than the upstream aggregate `{ templates, isExactMatch }`.
+ * - `useCaseId` is optional: `undefined` means "no use-case filter" (the wizard's
+ *   "Skip (show all)" choice), mirroring how {@link ANY_TEMPLATE_LANGUAGE} means
+ *   "no language filter".
+ *
+ * Templates are returned most- to least-fitting: exact matches first (in manifest order),
+ * then the language quick-start and empty templates, then same-language, then same-use-case,
+ * then everything else. Results are de-duplicated by `template.id`, preserving first insertion.
+ */
+export function getTemplateRecommendation(
+	templates: Template[],
+	useCaseId: string | undefined,
+	languageId: string,
+): TemplateRecommendation[] {
+	const hasLanguageFilter = languageId !== ANY_TEMPLATE_LANGUAGE;
+	const hasUseCaseFilter = useCaseId !== undefined;
+
+	const matchesLanguage = (template: Template) => !hasLanguageFilter || template.category === languageId;
+	const matchesUseCase = (template: Template) => !hasUseCaseFilter || (template.useCases?.includes(useCaseId) ?? false);
+	const isExactMatch = (template: Template) => matchesLanguage(template) && matchesUseCase(template);
+
+	const pickedIds = new Set<string>();
+	const picked: Template[] = [];
+
+	const addCandidates = (candidates: Template[]) => {
+		for (const candidate of candidates) {
+			if (!pickedIds.has(candidate.id)) {
+				pickedIds.add(candidate.id);
+				picked.push(candidate);
+			}
+		}
+	};
+
+	// Adds the curated template(s) from an id-per-language map: just the selected language's entry,
+	// or all of them when the language is "any". Missing entries match nothing.
+	const addCuratedTemplates = (idMap: Record<string, string | undefined>) => {
+		const ids = hasLanguageFilter ? [idMap[languageId]] : Object.values(idMap);
+		addCandidates(templates.filter((template) => ids.includes(template.id)));
+	};
+
+	// 1. Exact matches: everything the active filters accept.
+	addCandidates(templates.filter(isExactMatch));
+
+	// 2. Quick-start starter(s), then 3. empty template(s): curated per-language fallbacks.
+	addCuratedTemplates(QUICK_START_TEMPLATE_IDS);
+	addCuratedTemplates(EMPTY_TEMPLATE_IDS);
+
+	// 4. Same language, any use case.
+	if (hasLanguageFilter) {
+		addCandidates(templates.filter(matchesLanguage));
+	}
+
+	// 5. Same use case, any language.
+	if (hasUseCaseFilter) {
+		addCandidates(templates.filter(matchesUseCase));
+	}
+
+	// 6. Anything else, so the list is never shorter than the input.
+	addCandidates(templates);
+
+	return picked.map((template) => ({ template, isExactMatch: isExactMatch(template) }));
+}
diff --git a/src/lib/templates/templateChoices.ts b/src/lib/templates/templateChoices.ts
new file mode 100644
index 000000000..911a1511f
--- /dev/null
+++ b/src/lib/templates/templateChoices.ts
@@ -0,0 +1,71 @@
+import type { Template } from '@apify/actor-templates';
+
+import { ANY_TEMPLATE_LANGUAGE, LANGUAGE_OPTIONS, languageLabel, useCaseLabel } from './consts.js';
+import type { TemplateRecommendation } from './getTemplateRecommendation.js';
+
+/** Label of the non-selectable row that separates exact matches from the closest alternatives. */
+export const NON_EXACT_SEPARATOR_LABEL = "── The templates below don't exactly match your selection ──";
+
+export interface TemplateChoiceRow {
+	template: Template;
+	/** Display name, with a `(Language)` suffix when it differs from the user's selection. */
+	label: string;
+	isExactMatch: boolean;
+}
+
+export interface TemplateChoiceList {
+	rows: TemplateChoiceRow[];
+	/**
+	 * Index in `rows` before which the non-exact separator should be inserted (the first
+	 * non-exact template), or `null` when no separator is needed.
+	 */
+	separatorIndex: number | null;
+	/** Info line to show above the list when nothing matched exactly, or `null`. */
+	noExactMatchHint: string | null;
+}
+
+/**
+ * Turns a priority-ordered recommendation into the data a single-list template prompt needs:
+ * per-row labels, where to draw the "closest alternatives" separator, and the "no exact match"
+ * hint. Kept free of any prompt library so it can be unit-tested directly.
+ */
+export function buildTemplateChoiceList(
+	recommendations: TemplateRecommendation[],
+	useCaseId: string | undefined,
+	languageId: string,
+): TemplateChoiceList {
+	const hasExactMatch = recommendations.some((recommendation) => recommendation.isExactMatch);
+
+	const rows: TemplateChoiceRow[] = recommendations.map(({ template, isExactMatch }) => ({
+		template,
+		label: formatTemplateLabel(template, languageId),
+		isExactMatch,
+	}));
+
+	const firstNonExactIndex = rows.findIndex((row) => !row.isExactMatch);
+	const separatorIndex = hasExactMatch && firstNonExactIndex > 0 ? firstNonExactIndex : null;
+
+	const noExactMatchHint =
+		!hasExactMatch && rows.length > 0
+			? `No template matches ${describeSelection(useCaseId, languageId)} exactly — showing the closest alternatives.`
+			: null;
+
+	return { rows, separatorIndex, noExactMatchHint };
+}
+
+/** Appends a `(Language)` suffix when the template's language differs from the user's selection. */
+function formatTemplateLabel(template: Template, selectedLanguageId: string): string {
+	const label = LANGUAGE_OPTIONS.find((option) => option.id === template.category)?.label;
+	const differentLanguage = selectedLanguageId === ANY_TEMPLATE_LANGUAGE || template.category !== selectedLanguageId;
+
+	return label && differentLanguage ? `${template.label} (${label})` : template.label;
+}
+
+/** Human-readable "<use case> + <language>" description for the "no exact match" hint. */
+function describeSelection(useCaseId: string | undefined, languageId: string): string {
+	const parts: string[] = [];
+	if (useCaseId) parts.push(useCaseLabel(useCaseId));
+	parts.push(languageLabel(languageId));
+
+	return parts.join(' + ');
+}
diff --git a/test/local/lib/getTemplateRecommendation.test.ts b/test/local/lib/getTemplateRecommendation.test.ts
new file mode 100644
index 000000000..6f01cee96
--- /dev/null
+++ b/test/local/lib/getTemplateRecommendation.test.ts
@@ -0,0 +1,172 @@
+import type { Template } from '@apify/actor-templates';
+
+import { ANY_TEMPLATE_LANGUAGE, TEMPLATE_USE_CASES } from '../../../src/lib/templates/consts.js';
+import { getTemplateRecommendation } from '../../../src/lib/templates/getTemplateRecommendation.js';
+
+function makeTemplate(id: string, category: string, useCases?: string[]): Template {
+	return {
+		id,
+		name: id,
+		label: `Label ${id}`,
+		category,
+		technologies: [],
+		description: `Description ${id}`,
+		archiveUrl: `https://example.com/${id}.zip`,
+		...(useCases ? { useCases } : {}),
+	};
+}
+
+const { WEB_SCRAPING, AI, INTEGRATION, AUTOMATION, STARTER } = TEMPLATE_USE_CASES;
+
+// A synthetic manifest that exercises every tier. Order matters — it is the tie-break within a tier.
+const templates: Template[] = [
+	makeTemplate('js-crawlee-cheerio', 'javascript', [WEB_SCRAPING, STARTER]), // JS quick-start
+	makeTemplate('js-scraper', 'javascript', [WEB_SCRAPING]),
+	makeTemplate('js-integration', 'javascript', [INTEGRATION]),
+	makeTemplate('js-empty', 'javascript', [STARTER]), // JS empty
+	makeTemplate('ts-crawlee-cheerio', 'typescript', [WEB_SCRAPING, STARTER]), // TS quick-start
+	makeTemplate('ts-empty', 'typescript', [STARTER]), // TS empty
+	makeTemplate('ts-automation', 'typescript', [AUTOMATION]),
+	makeTemplate('python-crawlee-beautifulsoup', 'python', [WEB_SCRAPING, STARTER]), // Python quick-start
+	makeTemplate('python-ai', 'python', [AI]),
+	makeTemplate('python-empty', 'python', [STARTER]), // Python empty
+	makeTemplate('no-usecases', 'python'), // template lacking useCases
+];
+
+const ids = (recommendation: ReturnType<typeof getTemplateRecommendation>) => recommendation.map((r) => r.template.id);
+const exactIds = (recommendation: ReturnType<typeof getTemplateRecommendation>) =>
+	recommendation.filter((r) => r.isExactMatch).map((r) => r.template.id);
+
+describe('getTemplateRecommendation', () => {
+	it('always returns every template exactly once, in priority order', () => {
+		const result = getTemplateRecommendation(templates, WEB_SCRAPING, 'python');
+
+		expect(result).toHaveLength(templates.length);
+		expect(new Set(ids(result)).size).toBe(templates.length);
+	});
+
+	describe('specific language + use case', () => {
+		it('puts exact (language + use-case) matches first, in manifest order', () => {
+			const result = getTemplateRecommendation(templates, WEB_SCRAPING, 'python');
+
+			// Only the two Python WEB_SCRAPING templates are exact matches.
+			expect(exactIds(result)).toEqual(['python-crawlee-beautifulsoup']);
+			expect(result[0]).toMatchObject({ template: { id: 'python-crawlee-beautifulsoup' }, isExactMatch: true });
+		});
+
+		it('follows exact matches with the language quick-start, empty, then rest of the language', () => {
+			// Python + AI: exact is python-ai, then quick-start, empty, then remaining python templates.
+			const result = getTemplateRecommendation(templates, AI, 'python');
+
+			expect(exactIds(result)).toEqual(['python-ai']);
+			expect(ids(result).slice(0, 4)).toEqual([
+				'python-ai', // exact
+				'python-crawlee-beautifulsoup', // quick-start
+				'python-empty', // empty
+				'no-usecases', // remaining python (tier 4), then non-python fall-throughs
+			]);
+		});
+
+		it('does not duplicate a template that qualifies for several tiers', () => {
+			// python-crawlee-beautifulsoup is both an exact match and the quick-start.
+			const result = getTemplateRecommendation(templates, WEB_SCRAPING, 'python');
+			const occurrences = ids(result).filter((id) => id === 'python-crawlee-beautifulsoup');
+
+			expect(occurrences).toHaveLength(1);
+		});
+
+		it('marks every non-exact fallback template isExactMatch: false', () => {
+			const result = getTemplateRecommendation(templates, AI, 'python');
+			const nonExact = result.filter((r) => !r.isExactMatch);
+
+			expect(nonExact.every((r) => r.template.id !== 'python-ai')).toBe(true);
+		});
+	});
+
+	describe('no exact matches', () => {
+		it('flags nothing as exact but still returns the full list', () => {
+			// AUTOMATION + javascript has no exact match in the fixture (only ts-automation exists).
+			const result = getTemplateRecommendation(templates, AUTOMATION, 'javascript');
+
+			expect(exactIds(result)).toEqual([]);
+			expect(result).toHaveLength(templates.length);
+		});
+
+		it('prioritises the language quick-start and empty when the use case has no language match', () => {
+			const result = getTemplateRecommendation(templates, AUTOMATION, 'javascript');
+
+			expect(ids(result).slice(0, 2)).toEqual(['js-crawlee-cheerio', 'js-empty']);
+		});
+	});
+
+	describe('any language + use case', () => {
+		it('treats any use-case match as exact regardless of language', () => {
+			const result = getTemplateRecommendation(templates, WEB_SCRAPING, ANY_TEMPLATE_LANGUAGE);
+
+			expect(exactIds(result)).toEqual([
+				'js-crawlee-cheerio',
+				'js-scraper',
+				'ts-crawlee-cheerio',
+				'python-crawlee-beautifulsoup',
+			]);
+		});
+
+		it('falls back to all quick-starts then all empties', () => {
+			const result = getTemplateRecommendation(templates, AI, ANY_TEMPLATE_LANGUAGE);
+
+			// Only python-ai is exact; then all three quick-starts, then all three empties.
+			expect(exactIds(result)).toEqual(['python-ai']);
+			expect(ids(result).slice(0, 7)).toEqual([
+				'python-ai',
+				'js-crawlee-cheerio',
+				'ts-crawlee-cheerio',
+				'python-crawlee-beautifulsoup',
+				'js-empty',
+				'ts-empty',
+				'python-empty',
+			]);
+		});
+	});
+
+	describe('skip use case (show all)', () => {
+		it('treats a language-only match as exact when the use case is skipped', () => {
+			const result = getTemplateRecommendation(templates, undefined, 'typescript');
+
+			expect(exactIds(result)).toEqual(['ts-crawlee-cheerio', 'ts-empty', 'ts-automation']);
+		});
+
+		it('marks everything exact when both filters are skipped', () => {
+			const result = getTemplateRecommendation(templates, undefined, ANY_TEMPLATE_LANGUAGE);
+
+			expect(result.every((r) => r.isExactMatch)).toBe(true);
+			expect(ids(result)).toEqual(templates.map((t) => t.id));
+		});
+	});
+
+	describe('BYO-Docker / other language', () => {
+		it('finds no exact match and falls through to use-case then all templates', () => {
+			const result = getTemplateRecommendation(templates, WEB_SCRAPING, 'other');
+
+			expect(exactIds(result)).toEqual([]);
+			// use-case matches (any language) come before the remaining templates.
+			expect(ids(result).slice(0, 4)).toEqual([
+				'js-crawlee-cheerio',
+				'js-scraper',
+				'ts-crawlee-cheerio',
+				'python-crawlee-beautifulsoup',
+			]);
+			expect(result).toHaveLength(templates.length);
+		});
+	});
+
+	it('never treats a template without useCases as an exact match', () => {
+		const result = getTemplateRecommendation(templates, WEB_SCRAPING, 'python');
+		const noUseCases = result.find((r) => r.template.id === 'no-usecases');
+
+		expect(noUseCases?.isExactMatch).toBe(false);
+	});
+
+	it('returns an empty array for an empty template list', () => {
+		expect(getTemplateRecommendation([], WEB_SCRAPING, 'python')).toEqual([]);
+	});
+});
diff --git a/test/local/lib/templateChoices.test.ts b/test/local/lib/templateChoices.test.ts
new file mode 100644
index 000000000..b9b863cc5
--- /dev/null
+++ b/test/local/lib/templateChoices.test.ts
@@ -0,0 +1,92 @@
+import type { Template } from '@apify/actor-templates';
+
+import { ANY_TEMPLATE_LANGUAGE, TEMPLATE_USE_CASES } from '../../../src/lib/templates/consts.js';
+import { getTemplateRecommendation } from '../../../src/lib/templates/getTemplateRecommendation.js';
+import { buildTemplateChoiceList, NON_EXACT_SEPARATOR_LABEL } from '../../../src/lib/templates/templateChoices.js';
+
+function makeTemplate(id: string, category: string, label: string, useCases?: string[]): Template {
+	return {
+		id,
+		name: id,
+		label,
+		category,
+		technologies: [],
+		description: `Description ${id}`,
+		archiveUrl: `https://example.com/${id}.zip`,
+		...(useCases ? { useCases } : {}),
+	};
+}
+
+const { WEB_SCRAPING, AUTOMATION, STARTER, INTEGRATION } = TEMPLATE_USE_CASES;
+
+const templates: Template[] = [
+	makeTemplate('python-crawlee-beautifulsoup', 'python', 'Crawlee + BeautifulSoup', [WEB_SCRAPING, STARTER]),
+	makeTemplate('python-empty', 'python', 'Empty Python project', [STARTER]),
+	makeTemplate('python-standby', 'python', 'Standby Python project', [INTEGRATION]),
+	makeTemplate('js-crawlee-cheerio', 'javascript', 'Crawlee + Cheerio', [WEB_SCRAPING, STARTER]),
+	makeTemplate('js-empty', 'javascript', 'Empty JavaScript project', [STARTER]),
+];
+
+function buildFor(useCaseId: string | undefined, languageId: string) {
+	return buildTemplateChoiceList(getTemplateRecommendation(templates, useCaseId, languageId), useCaseId, languageId);
+}
+
+describe('buildTemplateChoiceList', () => {
+	it('places the separator right before the first non-exact template', () => {
+		const list = buildFor(WEB_SCRAPING, 'python');
+
+		// python-crawlee-beautifulsoup is the only exact match, so the separator goes at index 1.
+		expect(list.separatorIndex).toBe(1);
+		expect(list.rows[0]).toMatchObject({ isExactMatch: true, template: { id: 'python-crawlee-beautifulsoup' } });
+		expect(list.rows[1].isExactMatch).toBe(false);
+		expect(list.noExactMatchHint).toBeNull();
+	});
+
+	it('omits the suffix for same-language templates', () => {
+		const list = buildFor(WEB_SCRAPING, 'python');
+
+		expect(list.rows[0].label).toBe('Crawlee + BeautifulSoup');
+	});
+
+	it('adds a (Language) suffix for cross-language templates', () => {
+		const list = buildFor(WEB_SCRAPING, 'python');
+		const jsRow = list.rows.find((row) => row.template.id === 'js-crawlee-cheerio');
+
+		expect(jsRow?.label).toBe('Crawlee + Cheerio (JavaScript)');
+	});
+
+	it('adds a suffix to every row when any language is selected', () => {
+		const list = buildFor(WEB_SCRAPING, ANY_TEMPLATE_LANGUAGE);
+
+		expect(list.rows.every((row) => / \(\w/.test(row.label))).toBe(true);
+	});
+
+	it('has no separator when every template is an exact match', () => {
+		const list = buildFor(undefined, ANY_TEMPLATE_LANGUAGE);
+
+		expect(list.separatorIndex).toBeNull();
+		expect(list.noExactMatchHint).toBeNull();
+		expect(list.rows.every((row) => row.isExactMatch)).toBe(true);
+	});
+
+	it('emits a hint and no separator when nothing matches exactly', () => {
+		// AUTOMATION + javascript has no exact match in this fixture.
+		const list = buildFor(AUTOMATION, 'javascript');
+
+		expect(list.separatorIndex).toBeNull();
+		expect(list.rows.every((row) => !row.isExactMatch)).toBe(true);
+		expect(list.noExactMatchHint).toBe(
+			'No template matches Browser automation + JavaScript exactly — showing the closest alternatives.',
+		);
+	});
+
+	it('describes a skipped use case with only the language in the hint', () => {
+		const list = buildFor(undefined, 'other');
+
+		expect(list.noExactMatchHint).toBe('No template matches other exactly — showing the closest alternatives.');
+	});
+
+	it('uses the agreed separator label', () => {
+		expect(NON_EXACT_SEPARATOR_LABEL).toContain("don't exactly match your selection");
+	});
+});

From 4732e9ce7f8b7e5802711ef105c4a6bf1ca12ec6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Richard=20Sol=C3=A1r?= <solar.richard@gmail.com>
Date: Thu, 16 Jul 2026 12:22:06 +0200
Subject: [PATCH 2/2] test(create): cover flag mappings and --template
 precedence
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Assert `--use-case` / `--language` are ignored when `--template` is
  provided: a TypeScript template scaffolds unchanged despite conflicting
  python/ai filters.
- Unit-test the flag→id mappings (useCaseFlagToId, USE_CASE/LANGUAGE
  flag choices, labels), including that STARTER is never exposed.

Refs #1236

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 test/local/commands/create.test.ts    | 29 ++++++++++++++++++++
 test/local/lib/templateConsts.test.ts | 38 +++++++++++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 test/local/lib/templateConsts.test.ts

diff --git a/test/local/commands/create.test.ts b/test/local/commands/create.test.ts
index e32709d94..2dfa3a189 100644
--- a/test/local/commands/create.test.ts
+++ b/test/local/commands/create.test.ts
@@ -97,6 +97,35 @@ describe('apify create', () => {
 		).to.be.eql(expectedInput);
 	});
 
+	it('ignores --use-case and --language when --template is provided', async () => {
+		// A TypeScript template, deliberately paired with conflicting python/ai filters.
+		const ACT_TEMPLATE = 'getting_started_typescript';
+		const expectedInput = { url: 'https://www.apify.com' };
+
+		await testRunCommand(CreateCommand, {
+			args_actorName: actName,
+			flags_template: ACT_TEMPLATE,
+			flags_useCase: 'ai-agent',
+			flags_language: 'python',
+			flags_skipDependencyInstall: true,
+		});
+
+		expect(existsSync(tmpPath)).toBeTruthy();
+
+		toggleCwdBetweenFullAndParentPath();
+
+		const actorJsonPath = joinPath(LOCAL_CONFIG_PATH);
+
+		expect(existsSync(joinPath('package.json'))).toBeTruthy();
+		expect(existsSync(actorJsonPath)).toBeTruthy();
+		expect(JSON.parse(readFileSync(actorJsonPath, 'utf8')).name).to.be.eql(actName);
+		// The TypeScript template's prefilled input proves the --template value was used verbatim,
+		// not a template chosen by the (conflicting) --use-case / --language filters.
+		expect(
+			JSON.parse(readFileSync(joinPath(getLocalKeyValueStorePath(), `${KEY_VALUE_STORE_KEYS.INPUT}.json`), 'utf8')),
+		).to.be.eql(expectedInput);
+	});
+
 	it('should skip installing optional dependencies', async () => {
 		const ACT_TEMPLATE = 'project_cheerio_crawler_js';
 
diff --git a/test/local/lib/templateConsts.test.ts b/test/local/lib/templateConsts.test.ts
new file mode 100644
index 000000000..616a0cef4
--- /dev/null
+++ b/test/local/lib/templateConsts.test.ts
@@ -0,0 +1,38 @@
+import {
+	LANGUAGE_FLAG_CHOICES,
+	languageLabel,
+	TEMPLATE_USE_CASES,
+	USE_CASE_FLAG_CHOICES,
+	useCaseFlagToId,
+	useCaseLabel,
+} from '../../../src/lib/templates/consts.js';
+
+describe('template flag mappings', () => {
+	it('maps each --use-case flag value to its manifest id', () => {
+		expect(useCaseFlagToId('web-scraping')).toBe(TEMPLATE_USE_CASES.WEB_SCRAPING);
+		expect(useCaseFlagToId('ai-agent')).toBe(TEMPLATE_USE_CASES.AI);
+		expect(useCaseFlagToId('api-pipeline')).toBe(TEMPLATE_USE_CASES.INTEGRATION);
+		expect(useCaseFlagToId('browser-automation')).toBe(TEMPLATE_USE_CASES.AUTOMATION);
+	});
+
+	it('returns undefined for an unknown use-case flag', () => {
+		expect(useCaseFlagToId('nonsense')).toBeUndefined();
+	});
+
+	it('never exposes STARTER as a use-case flag, and every choice maps to a real id', () => {
+		expect(USE_CASE_FLAG_CHOICES).not.toContain('starter');
+		for (const flag of USE_CASE_FLAG_CHOICES) {
+			expect(useCaseFlagToId(flag)).toBeDefined();
+		}
+	});
+
+	it('accepts the three languages plus the BYO-Docker "other" value', () => {
+		expect(LANGUAGE_FLAG_CHOICES).toEqual(['javascript', 'typescript', 'python', 'other']);
+	});
+
+	it('labels use cases and languages for the "no exact match" hint', () => {
+		expect(useCaseLabel(TEMPLATE_USE_CASES.AUTOMATION)).toBe('Browser automation');
+		expect(languageLabel('javascript')).toBe('JavaScript');
+		expect(languageLabel('other')).toBe('other');
+	});
+});