From c10dcefd929065c6346d6a1b14985234876381f3 Mon Sep 17 00:00:00 2001
From: kuntal1461 <kuntal.1461@gmail.com>
Date: Sat, 3 Oct 2026 03:57:36 +0530
Subject: [PATCH 1/3] feat: add global --non-interactive flag and agent env var
 auto-detection
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes #1451 (prompt hang in pseudo-TTY environments) and #1354 (phantom --confirm flags).

P0 — global --non-interactive flag:
- New `src/lib/nonInteractiveMode.ts`: single source of truth with
  `isNonInteractive()`, `setNonInteractiveFlag()`, and `resetNonInteractiveFlag()`
- Registered `--non-interactive` in `_buildParseArgsOption()` alongside `--help`
  and `--user-agent`; env var `APIFY_CLI_NON_INTERACTIVE=1` is equivalent
- Activated early in `runCLI()` before version-check middleware; reset+re-applied
  at the start of every `_run()` for test isolation
- All three divergent interactivity decision points now converge on `isNonInteractive()`:
  `_stdinCheckWrapper`, `create.ts`, and `detectIsInteractive()` in telemetry
- Skipped prompt with no programmatic answer exits non-zero with an actionable message
  naming the exact flag to pass (fixes phantom `--confirm/--no-confirm` bug #1354)
- Added GLOBAL OPTIONS section to main `--help` output
- Added actionable `errorMessageForStdin` to previously unguarded prompts in
  `useActorConfig.ts` and `auth/login.ts`

P1 — agent env var auto-detection and skill update:
- `AGENT_ENV_VARS` (9 known agent runtimes) moved to `nonInteractiveMode.ts` and
  exported; `isNonInteractive()` returns true when any agent env var is set
- `detectEnvironment.ts` refactored to import `AGENT_ENV_VARS` from the single
  source (no duplication, no circular import)
- `skills/apify/SKILL.md`: added required "always pass --non-interactive" line
- `test/setup.ts` + `vitest.config.ts`: global Vitest setup clears agent env vars
  before each test file so host environment (e.g. CLAUDECODE) does not leak into tests

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .gitignore                                    |  1 +
 skills/apify/SKILL.md                         |  2 +
 src/commands/auth/login.ts                    |  6 +-
 src/commands/create.ts                        |  8 +-
 src/entrypoints/_shared.ts                    |  5 +
 src/lib/command-framework/apify-command.ts    | 12 +++
 src/lib/command-framework/help.ts             |  9 ++
 src/lib/hooks/telemetry/detectEnvironment.ts  | 16 +---
 src/lib/hooks/useActorConfig.ts               |  4 +
 .../user-confirmations/_stdinCheckWrapper.ts  |  8 +-
 src/lib/nonInteractiveMode.ts                 | 33 +++++++
 test/local/lib/nonInteractive.test.ts         | 91 +++++++++++++++++++
 test/setup.ts                                 |  6 ++
 vitest.config.ts                              |  1 +
 14 files changed, 180 insertions(+), 22 deletions(-)
 create mode 100644 src/lib/nonInteractiveMode.ts
 create mode 100644 test/local/lib/nonInteractive.test.ts
 create mode 100644 test/setup.ts

diff --git a/.gitignore b/.gitignore
index ae58d5467..c9bd1e449 100644
--- a/.gitignore
+++ b/.gitignore
@@ -27,3 +27,4 @@ package-lock.json
 scripts/temporary-reference.md
 
 bundles/*
+docs/dev-notes/
diff --git a/skills/apify/SKILL.md b/skills/apify/SKILL.md
index ffe0688ab..ae02f58ed 100644
--- a/skills/apify/SKILL.md
+++ b/skills/apify/SKILL.md
@@ -9,6 +9,8 @@ Run `apify -h` first to see the available commands and global options, then `api
 
 ## Non-interactive use
 
+Always pass `--non-interactive` (or set `APIFY_CLI_NON_INTERACTIVE=1`) when driving `apify` from an agent — it forces every prompt onto the skip path regardless of terminal detection and exits non-zero when a required answer has no flag equivalent.
+
 Many commands prompt when run interactively. To run without prompts, pass every required argument and flag explicitly:
 
 - `apify create <name> --template <template>` — skip the create wizard.
diff --git a/src/commands/auth/login.ts b/src/commands/auth/login.ts
index 959c99c2c..7186f6af2 100644
--- a/src/commands/auth/login.ts
+++ b/src/commands/auth/login.ts
@@ -211,7 +211,11 @@ export class AuthLoginCommand extends ApifyCommand<typeof AuthLoginCommand> {
 		} else {
 			console.log(`Enter your Apify API token. You can find it at ${consoleIntegrationsUrl}`);
 
-			const tokenAnswer = await useMaskedInput({ message: 'token:' });
+			const tokenAnswer = await useMaskedInput({
+				message: 'token:',
+				errorMessageForStdin:
+					'Pass --token <your-token> to log in non-interactively (e.g. apify login --token <value>).',
+			});
 			await tryToLogin(tokenAnswer);
 		}
 	}
diff --git a/src/commands/create.ts b/src/commands/create.ts
index f0b6ae75e..00b54fc9f 100644
--- a/src/commands/create.ts
+++ b/src/commands/create.ts
@@ -45,6 +45,7 @@ import { getInstallCommandSuggestion } from '../lib/hooks/runtimes/utils.js';
 import { ProjectLanguage, useCwdProject } from '../lib/hooks/useCwdProject.js';
 import { useStdin } from '../lib/hooks/useStdin.js';
 import { createPrefilledInputFileFromInputSchema } from '../lib/input_schema.js';
+import { isNonInteractive } from '../lib/nonInteractiveMode.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 {
@@ -200,14 +201,15 @@ export class CreateCommand extends ApifyCommand<typeof CreateCommand> {
 		// failed run is enough to learn what to pass.
 		const needsTemplate = !templateName && !templateArchiveUrl;
 
-		if (json && (!actorName || needsTemplate)) {
+		if ((json || isNonInteractive()) && (!actorName || needsTemplate)) {
 			const missing = [
 				...(actorName ? [] : ['the Actor name as an argument']),
 				...(needsTemplate ? ['--template <name>'] : []),
 			];
+			const modeFlag = json ? '--json' : '--non-interactive';
 			const templateHint = needsTemplate ? ' Run "apify templates ls" to list template names.' : '';
 
-			throw new Error(`--json runs non-interactively. Pass ${missing.join(' and ')}.${templateHint}`);
+			throw new Error(`${modeFlag} runs non-interactively. Pass ${missing.join(' and ')}.${templateHint}`);
 		}
 
 		let source = this.flags.source as GitSource | undefined;
@@ -285,7 +287,7 @@ export class CreateCommand extends ApifyCommand<typeof CreateCommand> {
 		// The prompt helpers cannot be relied on for this: `useStdin` marks any non-TTY stdin as having
 		// data, so their own non-interactive fallback only fires under CI.
 		const { isTTY } = await useStdin();
-		const isInteractive = isTTY && !isCI && !json;
+		const isInteractive = isTTY && !isCI && !json && !isNonInteractive();
 
 		// Last wizard step, matching the Console. A run that cannot be asked keeps the previous behaviour.
 		source ??= isInteractive ? await promptGitSource() : 'apify';
diff --git a/src/entrypoints/_shared.ts b/src/entrypoints/_shared.ts
index 363801f71..8064f434a 100644
--- a/src/entrypoints/_shared.ts
+++ b/src/entrypoints/_shared.ts
@@ -16,6 +16,7 @@ import { SUPPORTED_NODEJS_VERSION } from '../lib/consts.js';
 import { useCLIMetadata } from '../lib/hooks/useCLIMetadata.js';
 import { shouldSkipVersionCheck } from '../lib/hooks/useCLIVersionCheck.js';
 import { useCommandSuggestions } from '../lib/hooks/useCommandSuggestions.js';
+import { NON_INTERACTIVE_FLAG_NAME, setNonInteractiveFlag } from '../lib/nonInteractiveMode.js';
 import { error } from '../lib/outputs.js';
 import { cliDebugPrint } from '../lib/utils/cliDebugPrint.js';
 
@@ -171,6 +172,10 @@ export async function runCLI(entrypoint: string) {
 	printCLIVersionAndExitIfFlagUsed(startingResult);
 	printHelpAndExitIfFlagUsedOrNoCommandPassed(startingResult, entrypoint);
 
+	if (startingResult.values[NON_INTERACTIVE_FLAG_NAME] === true) {
+		setNonInteractiveFlag(true);
+	}
+
 	// MIDDLEWARE START //
 
 	await runVersionCheck(entrypoint, startingResult.positionals[0]);
diff --git a/src/lib/command-framework/apify-command.ts b/src/lib/command-framework/apify-command.ts
index 5a9a92ef9..d768d35c9 100644
--- a/src/lib/command-framework/apify-command.ts
+++ b/src/lib/command-framework/apify-command.ts
@@ -18,6 +18,7 @@ import { checkAndUpdateLastCommand } from '../hooks/telemetry/useTelemetryState.
 import { useCLIMetadata } from '../hooks/useCLIMetadata.js';
 import { ProjectLanguage, useCwdProject } from '../hooks/useCwdProject.js';
 import { useRentalSunsetNotice } from '../hooks/useRentalSunsetNotice.js';
+import { NON_INTERACTIVE_FLAG_NAME, resetNonInteractiveFlag, setNonInteractiveFlag } from '../nonInteractiveMode.js';
 import { error } from '../outputs.js';
 import type { ArgTag, TaggedArgBuilder } from './args.js';
 import { CommandError, CommandErrorCode } from './CommandError.js';
@@ -152,6 +153,11 @@ const userAgentFlagDefinition = {
 	multiple: false,
 } as const satisfies ParseArgsOptionDescriptor;
 
+const nonInteractiveFlagDefinition = {
+	type: 'boolean',
+	multiple: false,
+} as const satisfies ParseArgsOptionDescriptor;
+
 export const USER_AGENT_FLAG_NAME = 'user-agent';
 export const USER_AGENT_ENV_VAR = 'APIFY_CLI_USER_AGENT';
 export const USER_AGENT_MAX_LENGTH = 256;
@@ -315,6 +321,11 @@ export abstract class ApifyCommand<T extends typeof BuiltApifyCommand = typeof B
 		const startTime = Date.now();
 		const { values: rawFlags, positionals: rawArgs, tokens: rawTokens } = parseResult;
 
+		resetNonInteractiveFlag();
+		if (rawFlags[NON_INTERACTIVE_FLAG_NAME] === true) {
+			setNonInteractiveFlag(true);
+		}
+
 		if (rawFlags.help) {
 			this.ctor.printHelp();
 		}
@@ -731,6 +742,7 @@ export abstract class ApifyCommand<T extends typeof BuiltApifyCommand = typeof B
 	protected _buildParseArgsOption() {
 		const baseOptions: Record<string, ParseArgsOptionDescriptor> = {
 			help: helpFlagDefinition,
+			[NON_INTERACTIVE_FLAG_NAME]: nonInteractiveFlagDefinition,
 		};
 
 		if (USER_AGENT_SUPPORTED_ENTRYPOINTS.has(this.entrypoint)) {
diff --git a/src/lib/command-framework/help.ts b/src/lib/command-framework/help.ts
index e86676b9d..32e33077f 100644
--- a/src/lib/command-framework/help.ts
+++ b/src/lib/command-framework/help.ts
@@ -196,6 +196,15 @@ export function renderMainHelpMenu(entrypoint: string) {
 		result.push('');
 	}
 
+	result.push(chalk.bold('GLOBAL OPTIONS'));
+	result.push(
+		'  --non-interactive  Skip all prompts; exit non-zero if a required answer has no flag equivalent.',
+		`                     Env: APIFY_CLI_NON_INTERACTIVE=1`,
+		'  --help             Show help for a command.',
+		'  --version          Show CLI version.',
+		'',
+	);
+
 	result.push(
 		chalk.bold('LEARN MORE'),
 		`  Use '${entrypoint} <command> --help' for more information about a command.`,
diff --git a/src/lib/hooks/telemetry/detectEnvironment.ts b/src/lib/hooks/telemetry/detectEnvironment.ts
index c21cd0e36..35ed536a4 100644
--- a/src/lib/hooks/telemetry/detectEnvironment.ts
+++ b/src/lib/hooks/telemetry/detectEnvironment.ts
@@ -1,19 +1,9 @@
 import ciInfo from 'ci-info';
 
-const AI_AGENT_ENV_VARS: [string, string][] = [
-	['CLAUDECODE', 'claude_code'],
-	['CLAUDE_CODE_ENTRYPOINT', 'claude_code'],
-	['CURSOR_AGENT', 'cursor'],
-	['CLINE_ACTIVE', 'cline'],
-	['CODEX_SANDBOX', 'codex_cli'],
-	['CODEX_THREAD_ID', 'codex_cli'],
-	['GEMINI_CLI', 'gemini_cli'],
-	['OPENCODE', 'open_code'],
-	['OPENCLAW_SHELL', 'openclaw'],
-];
+import { AGENT_ENV_VARS, isNonInteractive } from '../../nonInteractiveMode.js';
 
 export function detectAiAgent(): string | undefined {
-	for (const [envVar, agent] of AI_AGENT_ENV_VARS) {
+	for (const [envVar, agent] of AGENT_ENV_VARS) {
 		if (process.env[envVar]) {
 			return agent;
 		}
@@ -31,5 +21,5 @@ export function detectCi(): { isCi: boolean; ciProvider: string | undefined } {
 }
 
 export function detectIsInteractive(): boolean {
-	return !!process.stdin.isTTY && !!process.stdout.isTTY;
+	return !isNonInteractive() && !!process.stdin.isTTY && !!process.stdout.isTTY;
 }
diff --git a/src/lib/hooks/useActorConfig.ts b/src/lib/hooks/useActorConfig.ts
index a8efe1985..47e5e66bd 100644
--- a/src/lib/hooks/useActorConfig.ts
+++ b/src/lib/hooks/useActorConfig.ts
@@ -110,6 +110,8 @@ export async function useActorConfig(
 async function handleBothConfigVersionsFound(deprecatedConfigPath: string) {
 	const confirmed = await useYesNoConfirm({
 		message: `The new version of Apify CLI uses the ".actor/actor.json" instead of the "apify.json" file. Since we have found both files in your Actor directory, "apify.json" will be renamed to "apify.json.deprecated". Going forward, all commands will use ".actor/actor.json". You can read about the differences between the old and the new config at https://github.com/apify/apify-cli/blob/master/MIGRATIONS.md. Do you want to continue?`,
+		errorMessageForStdin:
+			'Config migration required (apify.json must be renamed to apify.json.deprecated). Run this command in an interactive terminal to confirm, or rename the file manually. See MIGRATIONS.md.',
 	});
 
 	// If users refuse to migrate, 🤷
@@ -169,6 +171,8 @@ async function handleMigrationFlow(
 
 	const confirmed = await useYesNoConfirm({
 		message: `The new version of Apify CLI uses the ".actor/actor.json" instead of the "apify.json" file. Your "apify.json" file will be automatically updated to the new format under ".actor/actor.json". The original file will be renamed by adding the ".deprecated" suffix. Do you want to continue?`,
+		errorMessageForStdin:
+			'Config migration required (apify.json → .actor/actor.json). Run this command in an interactive terminal to confirm, or follow MIGRATIONS.md to migrate manually.',
 	});
 
 	if (!confirmed) {
diff --git a/src/lib/hooks/user-confirmations/_stdinCheckWrapper.ts b/src/lib/hooks/user-confirmations/_stdinCheckWrapper.ts
index dd2db6223..871c81273 100644
--- a/src/lib/hooks/user-confirmations/_stdinCheckWrapper.ts
+++ b/src/lib/hooks/user-confirmations/_stdinCheckWrapper.ts
@@ -2,6 +2,7 @@ import process from 'node:process';
 
 import { isCI } from 'ci-info';
 
+import { isNonInteractive } from '../../nonInteractiveMode.js';
 import { useStdin } from '../useStdin.js';
 
 /**
@@ -24,9 +25,6 @@ type NewFunctionArgs<Fn extends (...args: any[]) => any> = [
 	...AllButFirst<Parameters<Fn>>,
 ];
 
-const ConfirmFlag = 'confirm';
-const NoConfirmFlag = `no-${ConfirmFlag}`;
-
 interface StdinCheckWrapperOptions {
 	/**
 	 * When set, this value will be used in environments where stdin is not available to provide a custom error message.
@@ -43,7 +41,7 @@ interface StdinCheckWrapperOptions {
 export function stdinCheckWrapper<Fn extends (...args: any[]) => any>(
 	fn: Fn,
 	{
-		errorMessageForStdin = `Please use the --${ConfirmFlag}/--${NoConfirmFlag} flags to confirm the action.`,
+		errorMessageForStdin = `This command requires interactive input. Pass --non-interactive to skip all prompts (exits non-zero when a required answer has no flag equivalent). See --help for flags that answer specific prompts.`,
 	}: StdinCheckWrapperOptions = {},
 ): (...args: NewFunctionArgs<Fn>) => Promise<Awaited<ReturnType<Fn>>> {
 	return async (input, ...rest) => {
@@ -51,7 +49,7 @@ export function stdinCheckWrapper<Fn extends (...args: any[]) => any>(
 
 		const casted = input as StdinCheckWrapperInput<Awaited<ReturnType<Fn>>>;
 
-		if (isCI || (!isTTY && !hasData)) {
+		if (isNonInteractive() || isCI || (!isTTY && !hasData)) {
 			if (typeof casted.providedConfirmFromStdin === 'undefined') {
 				throw new Error(casted.errorMessageForStdin ?? errorMessageForStdin);
 			}
diff --git a/src/lib/nonInteractiveMode.ts b/src/lib/nonInteractiveMode.ts
new file mode 100644
index 000000000..70aa709c3
--- /dev/null
+++ b/src/lib/nonInteractiveMode.ts
@@ -0,0 +1,33 @@
+import process from 'node:process';
+
+export const NON_INTERACTIVE_FLAG_NAME = 'non-interactive';
+export const NON_INTERACTIVE_ENV_VAR = 'APIFY_CLI_NON_INTERACTIVE';
+
+// Kept here (not detectEnvironment.ts) to avoid a circular import — detectEnvironment.ts already imports from this module.
+export const AGENT_ENV_VARS: readonly [string, string][] = [
+	['CLAUDECODE', 'claude_code'],
+	['CLAUDE_CODE_ENTRYPOINT', 'claude_code'],
+	['CURSOR_AGENT', 'cursor'],
+	['CLINE_ACTIVE', 'cline'],
+	['CODEX_SANDBOX', 'codex_cli'],
+	['CODEX_THREAD_ID', 'codex_cli'],
+	['GEMINI_CLI', 'gemini_cli'],
+	['OPENCODE', 'open_code'],
+	['OPENCLAW_SHELL', 'openclaw'],
+];
+
+let _flagSet = false;
+
+export function isNonInteractive(): boolean {
+	return (
+		_flagSet || process.env[NON_INTERACTIVE_ENV_VAR] === '1' || AGENT_ENV_VARS.some(([envVar]) => !!process.env[envVar])
+	);
+}
+
+export function setNonInteractiveFlag(value: boolean): void {
+	_flagSet = value;
+}
+
+export function resetNonInteractiveFlag(): void {
+	_flagSet = false;
+}
diff --git a/test/local/lib/nonInteractive.test.ts b/test/local/lib/nonInteractive.test.ts
new file mode 100644
index 000000000..f39afa912
--- /dev/null
+++ b/test/local/lib/nonInteractive.test.ts
@@ -0,0 +1,91 @@
+import process from 'node:process';
+
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+import { CreateCommand } from '../../../src/commands/create.js';
+import { testRunCommand } from '../../../src/lib/command-framework/apify-command.js';
+import { detectIsInteractive } from '../../../src/lib/hooks/telemetry/detectEnvironment.js';
+import type { StdinCheckWrapperInput } from '../../../src/lib/hooks/user-confirmations/_stdinCheckWrapper.js';
+import { stdinCheckWrapper } from '../../../src/lib/hooks/user-confirmations/_stdinCheckWrapper.js';
+import {
+	AGENT_ENV_VARS,
+	isNonInteractive,
+	NON_INTERACTIVE_ENV_VAR,
+	resetNonInteractiveFlag,
+	setNonInteractiveFlag,
+} from '../../../src/lib/nonInteractiveMode.js';
+
+describe('nonInteractiveMode', () => {
+	// Save and clear all agent env vars before each test so isNonInteractive()
+	// starts from a clean baseline regardless of the host environment (e.g. Claude Code sets CLAUDECODE).
+	const savedAgentEnvVars: Record<string, string | undefined> = {};
+
+	beforeEach(() => {
+		for (const [envVar] of AGENT_ENV_VARS) {
+			savedAgentEnvVars[envVar] = process.env[envVar];
+			delete process.env[envVar];
+		}
+	});
+
+	afterEach(() => {
+		resetNonInteractiveFlag();
+		delete process.env[NON_INTERACTIVE_ENV_VAR];
+		for (const [envVar] of AGENT_ENV_VARS) {
+			if (savedAgentEnvVars[envVar] === undefined) {
+				delete process.env[envVar];
+			} else {
+				process.env[envVar] = savedAgentEnvVars[envVar];
+			}
+		}
+		process.exitCode = undefined;
+	});
+
+	test('isNonInteractive() returns false by default', () => {
+		expect(isNonInteractive()).toBe(false);
+	});
+
+	test('isNonInteractive() returns true when env var is set', () => {
+		process.env[NON_INTERACTIVE_ENV_VAR] = '1';
+		expect(isNonInteractive()).toBe(true);
+	});
+
+	test('isNonInteractive() returns true after setNonInteractiveFlag(true)', () => {
+		setNonInteractiveFlag(true);
+		expect(isNonInteractive()).toBe(true);
+	});
+
+	test('resetNonInteractiveFlag() clears flag set by setNonInteractiveFlag(true)', () => {
+		setNonInteractiveFlag(true);
+		resetNonInteractiveFlag();
+		expect(isNonInteractive()).toBe(false);
+	});
+
+	test('stdinCheckWrapper throws with non-interactive message when no providedConfirmFromStdin', async () => {
+		setNonInteractiveFlag(true);
+		const wrapped = stdinCheckWrapper(async (_input: StdinCheckWrapperInput<string>) => 'result');
+		await expect(wrapped({})).rejects.toThrow('This command requires interactive input. Pass --non-interactive');
+	});
+
+	test('stdinCheckWrapper returns providedConfirmFromStdin without prompting when non-interactive', async () => {
+		setNonInteractiveFlag(true);
+		const wrapped = stdinCheckWrapper(async (_input: StdinCheckWrapperInput<string>) => 'prompted-result');
+		const result = await wrapped({ providedConfirmFromStdin: 'confirmed' });
+		expect(result).toBe('confirmed');
+	});
+
+	test('detectIsInteractive() returns false when isNonInteractive() is true', () => {
+		setNonInteractiveFlag(true);
+		expect(detectIsInteractive()).toBe(false);
+	});
+
+	test('isNonInteractive() returns true when a known agent env var is set (CLAUDECODE)', () => {
+		process.env['CLAUDECODE'] = '1';
+		expect(isNonInteractive()).toBe(true);
+	});
+
+	test('create command with --non-interactive and no name/template exits non-zero with clear message', async () => {
+		process.env[NON_INTERACTIVE_ENV_VAR] = '1';
+		await testRunCommand(CreateCommand, {});
+		expect(process.exitCode).toBe(1);
+	});
+});
diff --git a/test/setup.ts b/test/setup.ts
new file mode 100644
index 000000000..b8f2928f1
--- /dev/null
+++ b/test/setup.ts
@@ -0,0 +1,6 @@
+import { AGENT_ENV_VARS } from '../src/lib/nonInteractiveMode.js';
+
+// Clear agent env vars so isNonInteractive() starts clean regardless of the host environment (e.g. CLAUDECODE is set inside Claude Code).
+for (const [envVar] of AGENT_ENV_VARS) {
+	delete process.env[envVar];
+}
diff --git a/vitest.config.ts b/vitest.config.ts
index 3e6eeb0ba..34df82624 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -11,6 +11,7 @@ export default defineConfig({
 	test: {
 		globals: true,
 		restoreMocks: true,
+		setupFiles: ['./test/setup.ts'],
 		testTimeout: 120_000 * multiplierFactor,
 		hookTimeout: 120_000 * multiplierFactor,
 		include: ['**/*.{test,spec}.?(c|m)[jt]s?(x)'],

From 1f3136cfb579e525bcd0375a6c640850979af7fa Mon Sep 17 00:00:00 2001
From: kuntal1461 <kuntal.1461@gmail.com>
Date: Mon, 5 Oct 2026 17:40:31 +0530
Subject: [PATCH 2/3] feat: add apify agent setup command (P0)

Adds apify agent setup -- auto-detects installed AI coding agents (Claude Code, Cursor, VS Code, Kiro, Codex, Antigravity) by env var and home-path heuristics, then configures them via MCP. Includes tier ladder, idempotency via state file, --client override, --json output, and 89 tests covering unit, integration, security, and edge cases.
---
 src/commands/_register.ts               |   2 +
 src/commands/agent/_index.ts            |  19 +
 src/commands/agent/setup.ts             | 334 +++++++++++++
 src/lib/agent/catalog.json              |  14 +
 src/lib/agent/catalog.ts                |  79 +++
 src/lib/agent/detection.ts              |  78 +++
 src/lib/agent/state.ts                  |  42 ++
 src/lib/consts.ts                       |   2 +
 test/local/commands/agent/setup.test.ts | 612 ++++++++++++++++++++++++
 test/local/lib/agent/catalog.test.ts    | 110 +++++
 test/local/lib/agent/detection.test.ts  | 175 +++++++
 test/local/lib/agent/state.test.ts      | 178 +++++++
 12 files changed, 1645 insertions(+)
 create mode 100644 src/commands/agent/_index.ts
 create mode 100644 src/commands/agent/setup.ts
 create mode 100644 src/lib/agent/catalog.json
 create mode 100644 src/lib/agent/catalog.ts
 create mode 100644 src/lib/agent/detection.ts
 create mode 100644 src/lib/agent/state.ts
 create mode 100644 test/local/commands/agent/setup.test.ts
 create mode 100644 test/local/lib/agent/catalog.test.ts
 create mode 100644 test/local/lib/agent/detection.test.ts
 create mode 100644 test/local/lib/agent/state.test.ts

diff --git a/src/commands/_register.ts b/src/commands/_register.ts
index b1cce10ce..09ac6b1b3 100644
--- a/src/commands/_register.ts
+++ b/src/commands/_register.ts
@@ -9,6 +9,7 @@ import { ActorGetValueCommand } from './actor/get-value.js';
 import { ActorPushDataCommand } from './actor/push-data.js';
 import { ActorSetValueCommand } from './actor/set-value.js';
 import { ActorsIndexCommand } from './actors/_index.js';
+import { AgentIndexCommand } from './agent/_index.js';
 import { ApiCommand } from './api.js';
 import { AuthIndexCommand } from './auth/_index.js';
 import { BuildsIndexCommand } from './builds/_index.js';
@@ -41,6 +42,7 @@ export const apifyCommands = [
 	// namespaces
 	ActorIndexCommand,
 	ActorsIndexCommand,
+	AgentIndexCommand,
 	AuthIndexCommand,
 	BuildsIndexCommand,
 	DatasetsIndexCommand,
diff --git a/src/commands/agent/_index.ts b/src/commands/agent/_index.ts
new file mode 100644
index 000000000..bfd693ccf
--- /dev/null
+++ b/src/commands/agent/_index.ts
@@ -0,0 +1,19 @@
+import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
+import { AgentSetupCommand } from './setup.js';
+
+export class AgentIndexCommand extends ApifyCommand<typeof AgentIndexCommand> {
+	static override name = 'agent' as const;
+
+	static override description =
+		'Configure AI coding agents to use Apify tools via MCP. Detects installed clients and applies the best available integration tier.';
+
+	static override group = 'Agent';
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#apify-agent';
+
+	static override subcommands = [AgentSetupCommand];
+
+	async run() {
+		this.printHelp();
+	}
+}
diff --git a/src/commands/agent/setup.ts b/src/commands/agent/setup.ts
new file mode 100644
index 000000000..17ffd129a
--- /dev/null
+++ b/src/commands/agent/setup.ts
@@ -0,0 +1,334 @@
+import process from 'node:process';
+
+import chalk from 'chalk';
+
+import { type ClientEntry, buildSetupMcpUrl, getClientEntry, type Tier } from '../../lib/agent/catalog.js';
+import { detectClients } from '../../lib/agent/detection.js';
+import { isClientConfigured, readAgentState, type AgentState, writeAgentState } from '../../lib/agent/state.js';
+import { resolveAuth } from '../../lib/auth.js';
+import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
+import { Flags, YesFlag } from '../../lib/command-framework/flags.js';
+import { CommandExitCodes } from '../../lib/consts.js';
+import { useYesNoConfirm } from '../../lib/hooks/user-confirmations/useYesNoConfirm.js';
+import {
+	clientNeedsToken,
+	getClientHandler,
+	isSupportedClient,
+	type ClientName,
+	SUPPORTED_CLIENTS,
+} from '../../lib/mcp/clients.js';
+import { error, simpleLog } from '../../lib/outputs.js';
+import { printJsonToStdout } from '../../lib/utils.js';
+
+type Outcome = 'installed' | 'already_configured' | 'failed';
+
+interface SetupResult {
+	client: string;
+	tier: string;
+	outcome: Outcome;
+	reason?: string;
+}
+
+/**
+ * Picks the highest tier the client supports AND the catalog has an artifact for.
+ * When a plugin entry would be selected but its spec is not yet published (plugin: null),
+ * falls back to mcp.
+ */
+function effectiveTier(entry: ClientEntry): Tier {
+	if (entry.maxTier === 'plugin' && entry.plugin === null) return 'mcp';
+	return entry.maxTier;
+}
+
+async function applyMcp(client: ClientName, mcpUrl: string, token: string): Promise<void> {
+	await getClientHandler(client)({ url: mcpUrl, token, yes: true });
+}
+
+async function applyForClient(client: ClientName, entry: ClientEntry, mcpUrl: string, token: string): Promise<void> {
+	const tier = effectiveTier(entry);
+
+	if (tier === 'plugin') {
+		// P1: plugin marketplace install — not yet implemented
+		throw new Error(`Plugin tier not yet available for '${client}'. Try again after a catalog update.`);
+	}
+
+	if (tier === 'skills+mcp' || tier === 'mcp') {
+		await applyMcp(client, mcpUrl, token);
+		return;
+	}
+
+	// manual tier: print instructions only
+	simpleLog({
+		message: [
+			`  Manual setup required for ${chalk.bold(client)}:`,
+			`    Add the Apify MCP server to your client's config.`,
+			`    URL: ${mcpUrl}`,
+		].join('\n'),
+	});
+}
+
+export class AgentSetupCommand extends ApifyCommand<typeof AgentSetupCommand> {
+	static override name = 'setup' as const;
+
+	static override description =
+		'Auto-detect installed AI coding agents and configure them to use Apify tools via MCP. Detects clients by binary, environment variable, and config directory, then applies the best available integration tier.';
+
+	static override group = 'Agent';
+
+	static override interactive = true;
+
+	static override interactiveNote =
+		'Prompts once before applying changes. Pass --yes to skip the prompt. Pass --non-interactive to suppress all prompts (exits non-zero when a required answer has no flag equivalent).';
+
+	static override enableJsonFlag = true;
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#apify-agent-setup';
+
+	static override examples = [
+		{
+			description: 'Auto-detect all installed agents and configure them.',
+			command: 'apify agent setup',
+		},
+		{
+			description: 'Configure Claude Code without a confirmation prompt.',
+			command: 'apify agent setup --client claude-code --yes',
+		},
+		{
+			description: 'Non-interactive setup from a CI script.',
+			command: 'apify agent setup --yes --json',
+		},
+	];
+
+	static override flags = {
+		...YesFlag('Skip the confirmation prompt and apply immediately.'),
+		client: Flags.string({
+			description: `Target a specific client instead of auto-detecting. One of: ${SUPPORTED_CLIENTS.join(', ')}.`,
+		}),
+	};
+
+	async run() {
+		const { yes, client: clientFlag, json } = this.flags;
+		const mcpUrl = buildSetupMcpUrl();
+
+		// ── Step 1: Determine candidate clients ───────────────────────────
+		let candidates: ClientName[];
+		if (clientFlag) {
+			if (!isSupportedClient(clientFlag)) {
+				error({
+					message: `Unknown client '${clientFlag}'. Supported: ${SUPPORTED_CLIENTS.join(', ')}.`,
+				});
+				process.exitCode = CommandExitCodes.InvalidInput;
+				return;
+			}
+			candidates = [clientFlag];
+		} else {
+			candidates = await detectClients();
+			if (candidates.length === 0) {
+				simpleLog({
+					message: [
+						'No supported AI coding agents detected on this machine.',
+						`Supported clients: ${SUPPORTED_CLIENTS.join(', ')}.`,
+						`To target a specific client, re-run with --client <name>.`,
+					].join('\n'),
+				});
+				if (json) printJsonToStdout({ clients: [] });
+				return;
+			}
+		}
+
+		// ── Step 2: Idempotency — split into already-configured vs new ─────
+		const existingState = await readAgentState();
+		const alreadyConfigured: ClientName[] = [];
+		const toInstall: ClientName[] = [];
+
+		for (const client of candidates) {
+			if (existingState && isClientConfigured(existingState, client)) {
+				alreadyConfigured.push(client);
+			} else {
+				toInstall.push(client);
+			}
+		}
+
+		const alreadyResults: SetupResult[] = alreadyConfigured.map((client) => {
+			const entry = getClientEntry(client);
+			return {
+				client,
+				tier: entry ? effectiveTier(entry) : 'mcp',
+				outcome: 'already_configured',
+			};
+		});
+
+		if (toInstall.length === 0) {
+			simpleLog({
+				message: 'All detected agents are already configured. Nothing to do.',
+			});
+			if (json) printJsonToStdout({ clients: alreadyResults });
+			return;
+		}
+
+		// ── Step 3: Resolve auth once for all clients that need a token ────
+		const auth = await resolveAuth();
+
+		const allRequireToken = toInstall.every((c) => clientNeedsToken(c));
+		if (allRequireToken && !auth) {
+			error({
+				message: `You are not logged in to Apify. Run 'apify login' first, or set APIFY_TOKEN.`,
+			});
+			process.exitCode = CommandExitCodes.MissingAuth;
+			return;
+		}
+
+		// ── Step 4: Show plan, confirm once ───────────────────────────────
+		const planLines = toInstall.map((client) => {
+			const entry = getClientEntry(client);
+			const tier = entry ? effectiveTier(entry) : 'mcp';
+			return `  ${chalk.bold(client)}  [${tier} tier]`;
+		});
+
+		simpleLog({
+			message: [
+				`\nWill configure Apify MCP for ${toInstall.length} agent${toInstall.length === 1 ? '' : 's'}:`,
+				...planLines,
+				`\n  MCP URL: ${mcpUrl}`,
+			].join('\n'),
+		});
+
+		if (alreadyConfigured.length > 0) {
+			simpleLog({
+				message: `\nAlready configured (no changes): ${alreadyConfigured.join(', ')}`,
+			});
+		}
+
+		const confirmed = await useYesNoConfirm({
+			message: `Apply the configuration above?`,
+			default: false,
+			providedConfirmFromStdin: yes || undefined,
+			errorMessageForStdin: `Re-run with --yes to skip this prompt.`,
+		});
+
+		if (!confirmed) {
+			simpleLog({ message: 'Aborted. No changes were made.' });
+			if (json) printJsonToStdout({ clients: alreadyResults });
+			return;
+		}
+
+		// ── Step 5: Apply per client ───────────────────────────────────────
+		const token = auth?.token ?? '';
+		const installResults: SetupResult[] = [];
+		let anyFailed = false;
+
+		for (const client of toInstall) {
+			const entry = getClientEntry(client);
+			if (!entry) {
+				error({
+					message: `Skipping '${client}': not found in catalog.`,
+				});
+				installResults.push({
+					client,
+					tier: 'mcp',
+					outcome: 'failed',
+					reason: 'not-in-catalog',
+				});
+				anyFailed = true;
+				continue;
+			}
+
+			if (clientNeedsToken(client) && !auth) {
+				error({
+					message: `Skipping '${client}': Apify token required. Run 'apify login' first.`,
+				});
+				installResults.push({
+					client,
+					tier: effectiveTier(entry),
+					outcome: 'failed',
+					reason: 'no-auth',
+				});
+				anyFailed = true;
+				continue;
+			}
+
+			// Some handlers (runCliInstall) signal failure via process.exitCode without throwing.
+			// Clear it before each client so we can detect a handler-set failure afterwards.
+			process.exitCode = undefined;
+			try {
+				await applyForClient(client, entry, mcpUrl, token);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				error({
+					message: `Failed to configure '${client}': ${message}`,
+				});
+				installResults.push({
+					client,
+					tier: effectiveTier(entry),
+					outcome: 'failed',
+					reason: message,
+				});
+				anyFailed = true;
+				process.exitCode = undefined;
+				continue;
+			}
+
+			if (process.exitCode !== undefined) {
+				// Handler set exitCode (e.g. binary not found) — treat as failure.
+				installResults.push({
+					client,
+					tier: effectiveTier(entry),
+					outcome: 'failed',
+					reason: `exit ${String(process.exitCode)}`,
+				});
+				anyFailed = true;
+				process.exitCode = undefined;
+			} else {
+				installResults.push({
+					client,
+					tier: effectiveTier(entry),
+					outcome: 'installed',
+				});
+			}
+		}
+
+		if (anyFailed) {
+			process.exitCode = CommandExitCodes.RunFailed;
+		}
+
+		// ── Step 6: Write state for newly installed clients ────────────────
+		const justInstalled = installResults.filter((r) => r.outcome === 'installed');
+		if (justInstalled.length > 0) {
+			const now = new Date().toISOString();
+			const newState: AgentState = existingState ?? {
+				installedAt: now,
+				clients: [],
+			};
+			if (!existingState) newState.installedAt = now;
+
+			for (const r of justInstalled) {
+				// Replace an existing entry if present (shouldn't happen given idempotency check, but safe)
+				const idx = newState.clients.findIndex((e) => e.client === r.client);
+				const record = {
+					client: r.client,
+					tier: r.tier,
+					installedAt: now,
+				};
+				if (idx >= 0) {
+					newState.clients[idx] = record;
+				} else {
+					newState.clients.push(record);
+				}
+			}
+
+			await writeAgentState(newState);
+		}
+
+		// ── Step 7: Machine-readable output ───────────────────────────────
+		if (json) {
+			// Sort: alreadyConfigured first, then installResults (preserves candidate order within each group)
+			const allResults = [...alreadyResults, ...installResults];
+			// Re-sort by original candidate order
+			const order = Object.fromEntries(candidates.map((c, i) => [c, i]));
+			allResults.sort((a, b) => (order[a.client] ?? 0) - (order[b.client] ?? 0));
+
+			printJsonToStdout({
+				clients: allResults.map(({ reason: _reason, ...rest }) => rest),
+			});
+		}
+	}
+}
diff --git a/src/lib/agent/catalog.json b/src/lib/agent/catalog.json
new file mode 100644
index 000000000..526b45b5c
--- /dev/null
+++ b/src/lib/agent/catalog.json
@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "mcpUrl": "https://mcp.apify.com",
+  "skillsRepo": "https://github.com/apify/agent-skills",
+  "clients": {
+    "claude-code": { "maxTier": "mcp", "plugin": null },
+    "cursor": { "maxTier": "mcp", "plugin": null },
+    "vscode": { "maxTier": "mcp", "plugin": null },
+    "vscode-insiders": { "maxTier": "mcp", "plugin": null },
+    "codex": { "maxTier": "mcp", "plugin": null },
+    "kiro": { "maxTier": "mcp", "plugin": null },
+    "antigravity": { "maxTier": "mcp", "plugin": null }
+  }
+}
diff --git a/src/lib/agent/catalog.ts b/src/lib/agent/catalog.ts
new file mode 100644
index 000000000..df3d18a51
--- /dev/null
+++ b/src/lib/agent/catalog.ts
@@ -0,0 +1,79 @@
+import rawCatalog from './catalog.json' with { type: 'json' };
+
+export type Tier = 'plugin' | 'skills+mcp' | 'mcp' | 'manual';
+export const TIER_ORDER = ['plugin', 'skills+mcp', 'mcp', 'manual'] as const satisfies readonly Tier[];
+
+export interface PluginEntry {
+	id: string;
+	marketplace: string; // forward-compat: P1 catalog refresh may introduce new marketplace values
+}
+
+export interface ClientEntry {
+	maxTier: Tier;
+	plugin: PluginEntry | null;
+}
+
+export interface Catalog {
+	version: number;
+	mcpUrl: string;
+	skillsRepo: string;
+	clients: Record<string, ClientEntry>;
+}
+
+function isPluginEntry(value: unknown): value is PluginEntry {
+	if (typeof value !== 'object' || value === null) return false;
+	const v = value as Record<string, unknown>;
+	return typeof v.id === 'string' && typeof v.marketplace === 'string';
+}
+
+export function isKnownTier(value: unknown): value is Tier {
+	// Widen the array type so unknown is accepted without casting value — safer than `value as Tier`.
+	return (TIER_ORDER as readonly unknown[]).includes(value);
+}
+
+function validateCatalog(raw: unknown): Catalog {
+	if (typeof raw !== 'object' || raw === null) throw new Error('catalog.json: root must be an object');
+	const r = raw as Record<string, unknown>;
+	if (typeof r.version !== 'number') throw new Error('catalog.json: missing or invalid "version" field');
+	if (typeof r.mcpUrl !== 'string') throw new Error('catalog.json: missing or invalid "mcpUrl" field');
+	if (typeof r.skillsRepo !== 'string') throw new Error('catalog.json: missing or invalid "skillsRepo" field');
+	if (typeof r.clients !== 'object' || r.clients === null)
+		throw new Error('catalog.json: missing or invalid "clients" field');
+	const clients = r.clients as Record<string, unknown>;
+	for (const key of Object.keys(clients)) {
+		const entry = clients[key];
+		if (typeof entry !== 'object' || entry === null) throw new Error(`catalog.json: client "${key}" must be an object`);
+		const e = entry as Record<string, unknown>;
+		if (!isKnownTier(e.maxTier)) throw new Error(`catalog.json: client "${key}" has invalid "maxTier"`);
+		if (e.plugin !== null && !isPluginEntry(e.plugin))
+			throw new Error(`catalog.json: client "${key}" has invalid "plugin"`);
+	}
+	return {
+		version: r.version as number,
+		mcpUrl: r.mcpUrl as string,
+		skillsRepo: r.skillsRepo as string,
+		clients: clients as Record<string, ClientEntry>,
+	};
+}
+
+// Validate at module load time so a malformed bundled JSON fails fast.
+const catalog: Catalog = validateCatalog(rawCatalog);
+
+export function getCatalog(): Catalog {
+	return catalog;
+}
+
+export function getClientEntry(id: string): ClientEntry | undefined {
+	return catalog.clients[id];
+}
+
+export function compareTiers(a: Tier, b: Tier): number {
+	return TIER_ORDER.indexOf(a) - TIER_ORDER.indexOf(b);
+}
+
+// TODO(#1445 P1): catalog.mcpUrl duplicates DEFAULT_MCP_URL in src/lib/mcp/url.ts and APIFY_MCP_URL in apify/apify-mcp-server. Converge after maintainer sign-off.
+export function buildSetupMcpUrl(base?: string): string {
+	const url = new URL(base ?? catalog.mcpUrl);
+	url.searchParams.set('client', 'apify-cli');
+	return url.toString();
+}
diff --git a/src/lib/agent/detection.ts b/src/lib/agent/detection.ts
new file mode 100644
index 000000000..097e27cbd
--- /dev/null
+++ b/src/lib/agent/detection.ts
@@ -0,0 +1,78 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+
+import which from 'which';
+
+import { type ClientName, SUPPORTED_CLIENTS } from '../mcp/clients.js';
+import { AGENT_ENV_VARS } from '../nonInteractiveMode.js';
+import { userHomeDir } from '../utils.js';
+
+// Maps the agent identifier used in AGENT_ENV_VARS to the catalog client key.
+const AGENT_ID_TO_CLIENT: Partial<Record<string, ClientName>> = {
+	claude_code: 'claude-code',
+	cursor: 'cursor',
+	codex_cli: 'codex',
+	openclaw: 'antigravity',
+};
+
+interface DetectionStrategy {
+	binaries?: string[]; // any on PATH → detected
+	homePaths?: string[]; // relative to ~, any exists → detected
+}
+
+// Per-client detection signals. Env-var detection is handled separately via AGENT_ENV_VARS.
+const DETECTION_MAP: Partial<Record<ClientName, DetectionStrategy>> = {
+	'claude-code': { binaries: ['claude'], homePaths: ['.claude'] },
+	cursor: { binaries: ['cursor'], homePaths: ['.cursor/mcp.json'] },
+	vscode: { binaries: ['code'], homePaths: ['.vscode'] },
+	'vscode-insiders': { binaries: ['code-insiders'], homePaths: ['.vscode-insiders'] },
+	codex: { binaries: ['codex'] },
+	kiro: { homePaths: ['.kiro'] },
+	antigravity: { homePaths: ['.gemini/antigravity'] },
+};
+
+function detectFromEnv(): Set<ClientName> {
+	const found = new Set<ClientName>();
+	for (const [envVar, agentId] of AGENT_ENV_VARS) {
+		if (process.env[envVar]) {
+			const client = AGENT_ID_TO_CLIENT[agentId];
+			if (client) found.add(client);
+		}
+	}
+	return found;
+}
+
+async function detectFromBinariesAndPaths(): Promise<Set<ClientName>> {
+	const home = userHomeDir();
+	const results = await Promise.all(
+		SUPPORTED_CLIENTS.map(async (client) => {
+			const strategy = DETECTION_MAP[client];
+			if (!strategy) return null;
+
+			for (const bin of strategy.binaries ?? []) {
+				if (await which(bin, { nothrow: true })) return client;
+			}
+
+			if (home) {
+				for (const rel of strategy.homePaths ?? []) {
+					if (existsSync(join(home, rel))) return client;
+				}
+			}
+
+			return null;
+		}),
+	);
+	return new Set(results.filter((c): c is ClientName => c !== null));
+}
+
+/**
+ * Returns catalog clients detected on this machine.
+ * Env-var-detected clients (agent is currently active) come first,
+ * then binary/path-detected clients (installed but not currently running).
+ */
+export async function detectClients(): Promise<ClientName[]> {
+	const envSet = detectFromEnv();
+	const fsSet = await detectFromBinariesAndPaths();
+	return [...new Set([...envSet, ...fsSet])];
+}
diff --git a/src/lib/agent/state.ts b/src/lib/agent/state.ts
new file mode 100644
index 000000000..fe12ffe77
--- /dev/null
+++ b/src/lib/agent/state.ts
@@ -0,0 +1,42 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import process from 'node:process';
+
+import { AGENT_STATE_FILE_PATH } from '../consts.js';
+
+export interface ClientStateRecord {
+	client: string;
+	tier: string;
+	installedAt: string; // ISO 8601
+}
+
+export interface AgentState {
+	installedAt: string; // timestamp of first apify agent setup run
+	clients: ClientStateRecord[];
+}
+
+export async function readAgentState(): Promise<AgentState | null> {
+	try {
+		const text = await readFile(AGENT_STATE_FILE_PATH(), 'utf-8');
+		return JSON.parse(text) as AgentState;
+	} catch {
+		return null;
+	}
+}
+
+export function isClientConfigured(state: AgentState, client: string): boolean {
+	return state.clients.some((r) => r.client === client);
+}
+
+export async function writeAgentState(state: AgentState): Promise<void> {
+	const filePath = AGENT_STATE_FILE_PATH();
+	await mkdir(dirname(filePath), { recursive: true });
+	const tmpPath = `${filePath}.${process.pid}.tmp`;
+	try {
+		await writeFile(tmpPath, `${JSON.stringify(state, null, 2)}\n`, 'utf-8');
+		await rename(tmpPath, filePath);
+	} catch (err) {
+		await rm(tmpPath, { force: true });
+		throw err;
+	}
+}
diff --git a/src/lib/consts.ts b/src/lib/consts.ts
index 6368135b0..3c118fe80 100644
--- a/src/lib/consts.ts
+++ b/src/lib/consts.ts
@@ -58,6 +58,8 @@ export const STATE_FILE_PATH = () => join(GLOBAL_CONFIGS_FOLDER(), 'state.json')
 
 export const TELEMETRY_FILE_PATH = () => join(GLOBAL_CONFIGS_FOLDER(), 'telemetry.json');
 
+export const AGENT_STATE_FILE_PATH = () => join(GLOBAL_CONFIGS_FOLDER(), 'agent-state.json');
+
 export const DEPRECATED_LOCAL_CONFIG_NAME = 'apify.json';
 
 export const ACTOR_SPECIFICATION_FOLDER = '.actor';
diff --git a/test/local/commands/agent/setup.test.ts b/test/local/commands/agent/setup.test.ts
new file mode 100644
index 000000000..a9f5fb112
--- /dev/null
+++ b/test/local/commands/agent/setup.test.ts
@@ -0,0 +1,612 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import process from 'node:process';
+
+// Force stdinCheckWrapper down its non-interactive path so prompts never block on stdin.
+vitest.mock('ci-info', async (importOriginal) => {
+	const original = await importOriginal<typeof import('ci-info')>();
+	return { ...original, isCI: true };
+});
+
+import { AgentSetupCommand } from '../../../../src/commands/agent/setup.js';
+import {
+	isClientConfigured,
+	readAgentState,
+	writeAgentState,
+	type AgentState,
+} from '../../../../src/lib/agent/state.js';
+import { testRunCommand } from '../../../../src/lib/command-framework/apify-command.js';
+import { CommandExitCodes } from '../../../../src/lib/consts.js';
+import { SUPPORTED_CLIENTS } from '../../../../src/lib/mcp/clients.js';
+import { useAuthSetup } from '../../../__setup__/hooks/useAuthSetup.js';
+import { useConsoleSpy } from '../../../__setup__/hooks/useConsoleSpy.js';
+import { useTempPath } from '../../../__setup__/hooks/useTempPath.js';
+
+const TEST_TOKEN = 'apify_api_TEST_xxxxxxxxxxxxxxxxxxxxxx';
+
+const { tmpPath, joinPath, beforeAllCalls, afterAllCalls } = useTempPath('agent-setup');
+
+useAuthSetup();
+const { logMessages } = useConsoleSpy();
+
+beforeAll(beforeAllCalls);
+afterAll(afterAllCalls);
+
+beforeEach(async () => {
+	// Wipe and recreate the fakeHome so each test starts from a clean ~.
+	await rm(tmpPath, { recursive: true, force: true });
+	await mkdir(tmpPath, { recursive: true });
+	// Route userHomeDir() lookups (client config paths like ~/.cursor/mcp.json) into tmpPath.
+	vitest.stubEnv('HOME', tmpPath);
+	// Empty PATH → which() returns null for every binary → no binary-based detection.
+	vitest.stubEnv('PATH', '');
+});
+
+afterEach(() => {
+	process.exitCode = undefined;
+});
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+async function readCursorConfig(): Promise<Record<string, unknown>> {
+	return JSON.parse(await readFile(joinPath('.cursor', 'mcp.json'), 'utf-8')) as Record<string, unknown>;
+}
+
+function parsedJsonOutput(): Record<string, unknown> {
+	const raw = logMessages.log.find((m) => m.startsWith('{'));
+	if (!raw) throw new Error('No JSON output found in stdout');
+	return JSON.parse(raw) as Record<string, unknown>;
+}
+
+async function makeCursorDetectable(): Promise<void> {
+	await mkdir(joinPath('.cursor'), { recursive: true });
+	await writeFile(joinPath('.cursor', 'mcp.json'), '{}', 'utf-8');
+}
+
+async function seedState(clients: string[]): Promise<void> {
+	const now = new Date().toISOString();
+	const state: AgentState = {
+		installedAt: now,
+		clients: clients.map((c) => ({
+			client: c,
+			tier: 'mcp',
+			installedAt: now,
+		})),
+	};
+	await writeAgentState(state);
+}
+
+// ── Detection ────────────────────────────────────────────────────────────────
+
+describe('apify agent setup', () => {
+	describe('detection', () => {
+		it('prints a no-agents message and exits 0 when nothing is detected', async () => {
+			await testRunCommand(AgentSetupCommand, {});
+
+			expect(process.exitCode).toBeUndefined();
+			const stderr = logMessages.error.join('\n');
+			expect(stderr).toMatch(/No supported AI coding agents detected/);
+			for (const client of SUPPORTED_CLIENTS) {
+				expect(stderr).toContain(client);
+			}
+		});
+
+		it('includes --client hint in the no-agents message', async () => {
+			await testRunCommand(AgentSetupCommand, {});
+			expect(logMessages.error.join('\n')).toMatch(/--client/);
+		});
+
+		it('--json with no agents outputs { clients: [] } to stdout and exits 0', async () => {
+			await testRunCommand(AgentSetupCommand, { flags_json: true });
+
+			expect(process.exitCode).toBeUndefined();
+			expect(parsedJsonOutput()).toEqual({ clients: [] });
+		});
+
+		it('CURSOR_AGENT env var causes cursor to appear in the plan', async () => {
+			vitest.stubEnv('CURSOR_AGENT', '1');
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			// Don't confirm — this just checks the plan message before the prompt.
+			await testRunCommand(AgentSetupCommand, {});
+
+			// With isCI=true and no --yes, the prompt throws. The error message shows the plan was reached.
+			const stderr = logMessages.error.join('\n');
+			expect(stderr).toMatch(/cursor/);
+		});
+
+		it('~/.cursor/mcp.json exists → cursor appears in plan', async () => {
+			await makeCursorDetectable();
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, {});
+
+			const stderr = logMessages.error.join('\n');
+			expect(stderr).toMatch(/cursor/);
+		});
+	});
+
+	// ── --client flag ─────────────────────────────────────────────────────────
+
+	describe('--client flag', () => {
+		it('rejects an unknown client name with InvalidInput exit code', async () => {
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'notaclient',
+			});
+
+			expect(process.exitCode).toBe(CommandExitCodes.InvalidInput);
+			expect(logMessages.error.join('\n')).toMatch(/Unknown client 'notaclient'/);
+		});
+
+		it('--client cursor bypasses detection even when nothing is installed', async () => {
+			// No home paths, no env vars — cursor is NOT auto-detected.
+			// --client forces the target without detection.
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			expect(process.exitCode).toBeUndefined();
+			const config = await readCursorConfig();
+			expect(config).toHaveProperty('mcpServers');
+		});
+	});
+
+	// ── Auth ─────────────────────────────────────────────────────────────────
+
+	describe('auth', () => {
+		it('MissingAuth when all detected clients need a token and no auth exists', async () => {
+			await makeCursorDetectable();
+			// No APIFY_TOKEN, no stored login (useAuthSetup ensures clean state).
+
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			expect(process.exitCode).toBe(CommandExitCodes.MissingAuth);
+			expect(logMessages.error.join('\n')).toMatch(/not logged in to Apify/);
+		});
+
+		it('APIFY_TOKEN env var is used as auth without apify login', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			expect(process.exitCode).toBeUndefined();
+			const config = await readCursorConfig();
+			const auth = (
+				config.mcpServers as {
+					apify: { headers: { Authorization: string } };
+				}
+			).apify.headers.Authorization;
+			expect(auth).toBe(`Bearer ${TEST_TOKEN}`);
+		});
+
+		it('codex (tokenless) — MissingAuth is NOT raised even with no auth', async () => {
+			// codex reads APIFY_TOKEN at runtime. The install itself needs no token.
+			// With PATH='', the codex binary is not found → the handler sets exitCode internally,
+			// and setup.ts normalises multi-client failures to RunFailed (1). The key assertion
+			// is that MissingAuth is NOT the reason for failure.
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'codex',
+				flags_yes: true,
+			});
+
+			expect(process.exitCode).toBe(CommandExitCodes.RunFailed);
+			expect(logMessages.error.join('\n')).not.toMatch(/not logged in to Apify/);
+		});
+	});
+
+	// ── Confirmation prompt ───────────────────────────────────────────────────
+
+	describe('confirmation prompt', () => {
+		it('isCI=true without --yes throws "Re-run with --yes" error', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+
+			await testRunCommand(AgentSetupCommand, { flags_client: 'cursor' });
+
+			// Command should fail because stdinCheckWrapper throws on non-interactive path with no providedConfirmFromStdin.
+			expect(process.exitCode).toBeDefined();
+			expect(logMessages.error.join('\n')).toMatch(/Re-run with --yes/);
+		});
+
+		it('--yes skips the prompt and proceeds', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			expect(process.exitCode).toBeUndefined();
+		});
+
+		it('declining the prompt (no --yes, non-interactive fallback is false) exits 0 with no changes', async () => {
+			// stdinCheckWrapper with providedConfirmFromStdin=undefined throws — we verify the right error.
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, { flags_client: 'cursor' });
+
+			// No cursor config written because prompt was not answered.
+			const { existsSync } = await import('node:fs');
+			expect(existsSync(joinPath('.cursor', 'mcp.json'))).toBe(false);
+		});
+	});
+
+	// ── Happy-path install ────────────────────────────────────────────────────
+
+	describe('happy path', () => {
+		it('cursor: installs via --client, writes config and state file', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			expect(process.exitCode).toBeUndefined();
+
+			// Client config written
+			const config = await readCursorConfig();
+			expect(config).toHaveProperty('mcpServers.apify');
+
+			// State file written
+			const state = await readAgentState();
+			expect(state).not.toBeNull();
+			expect(isClientConfigured(state!, 'cursor')).toBe(true);
+		});
+
+		it('cursor: state entry has the correct shape (client, tier, installedAt)', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const state = await readAgentState();
+			const entry = state!.clients.find((c) => c.client === 'cursor')!;
+			expect(entry).toMatchObject({ client: 'cursor', tier: 'mcp' });
+			expect(new Date(entry.installedAt).getTime()).toBeGreaterThan(0);
+		});
+
+		it('state file has a top-level installedAt on first run', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const state = await readAgentState();
+			expect(state?.installedAt).toBeDefined();
+			expect(new Date(state!.installedAt).getTime()).toBeGreaterThan(0);
+		});
+
+		it('success message appears in stderr for cursor', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			expect(logMessages.error.join('\n')).toMatch(/Success: Apify MCP server configured for Cursor/);
+		});
+	});
+
+	// ── MCP URL attribution ───────────────────────────────────────────────────
+
+	describe('MCP URL', () => {
+		it('cursor config URL contains ?client=apify-cli attribution tag', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const config = await readCursorConfig();
+			const { url } = (config.mcpServers as { apify: { url: string } }).apify;
+			expect(url).toContain('client=apify-cli');
+		});
+
+		it('cursor config URL does NOT duplicate client= when agent setup is re-run', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+
+			// First run
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			// State is already there — second run sees already_configured and stops before install.
+			// Manually clear state to force a second install and check the URL isn't doubled.
+			await writeAgentState({
+				installedAt: new Date().toISOString(),
+				clients: [],
+			});
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const config = await readCursorConfig();
+			const { url } = (config.mcpServers as { apify: { url: string } }).apify;
+			const count = (url.match(/client=apify-cli/g) ?? []).length;
+			expect(count).toBe(1);
+		});
+
+		it('MCP URL starts with https://mcp.apify.com', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const config = await readCursorConfig();
+			const { url } = (config.mcpServers as { apify: { url: string } }).apify;
+			expect(url).toMatch(/^https:\/\/mcp\.apify\.com/);
+		});
+	});
+
+	// ── Idempotency ───────────────────────────────────────────────────────────
+
+	describe('idempotency', () => {
+		it('pre-existing state entry → outcome=already_configured, no re-install', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await seedState(['cursor']);
+
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+				flags_json: true,
+			});
+
+			expect(process.exitCode).toBeUndefined();
+			const json = parsedJsonOutput();
+			const clients = json.clients as {
+				client: string;
+				outcome: string;
+			}[];
+			expect(clients.find((c) => c.client === 'cursor')?.outcome).toBe('already_configured');
+
+			// No cursor config written by this run (install was skipped).
+			const { existsSync } = await import('node:fs');
+			expect(existsSync(joinPath('.cursor', 'mcp.json'))).toBe(false);
+		});
+
+		it('all targets already configured → "Nothing to do" message, exits 0', async () => {
+			await seedState(['cursor']);
+
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			expect(process.exitCode).toBeUndefined();
+			expect(logMessages.error.join('\n')).toMatch(/already configured.*Nothing to do/i);
+		});
+
+		it('second run after real install returns already_configured', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+			expect(process.exitCode).toBeUndefined();
+
+			// Reset output counters
+			logMessages.log.length = 0;
+			logMessages.error.length = 0;
+			process.exitCode = undefined;
+
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+				flags_json: true,
+			});
+
+			const json = parsedJsonOutput();
+			const clients = json.clients as {
+				client: string;
+				outcome: string;
+			}[];
+			expect(clients.find((c) => c.client === 'cursor')?.outcome).toBe('already_configured');
+		});
+
+		it('state file installedAt is preserved (not updated) on already_configured run', async () => {
+			const originalTs = '2026-01-01T00:00:00.000Z';
+			await seedState(['cursor']);
+			const originalState = await readAgentState();
+			// Manually set installedAt to a known value
+			originalState!.installedAt = originalTs;
+			await writeAgentState(originalState!);
+
+			// Second run
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const state = await readAgentState();
+			expect(state?.installedAt).toBe(originalTs);
+		});
+
+		it('new client added without modifying existing entries', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			const cursorTs = '2025-06-01T00:00:00.000Z';
+			await writeAgentState({
+				installedAt: cursorTs,
+				clients: [{ client: 'cursor', tier: 'mcp', installedAt: cursorTs }],
+			});
+
+			// Install kiro as a new client
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'kiro',
+				flags_yes: true,
+			});
+
+			const state = await readAgentState();
+			// cursor entry should be unchanged
+			const cursorEntry = state!.clients.find((c) => c.client === 'cursor');
+			expect(cursorEntry?.installedAt).toBe(cursorTs);
+			// kiro entry should be present
+			expect(isClientConfigured(state!, 'kiro')).toBe(true);
+		});
+	});
+
+	// ── --json output ─────────────────────────────────────────────────────────
+
+	describe('--json output', () => {
+		it('output shape: { clients: [{ client, tier, outcome }] }', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+				flags_json: true,
+			});
+
+			const json = parsedJsonOutput();
+			expect(json).toHaveProperty('clients');
+			const clients = json.clients as Record<string, unknown>[];
+			expect(clients.length).toBeGreaterThan(0);
+			const entry = clients[0];
+			expect(entry).toHaveProperty('client');
+			expect(entry).toHaveProperty('tier');
+			expect(entry).toHaveProperty('outcome');
+		});
+
+		it('outcome is "installed" for a fresh install', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+				flags_json: true,
+			});
+
+			const clients = parsedJsonOutput().clients as {
+				client: string;
+				outcome: string;
+			}[];
+			expect(clients.find((c) => c.client === 'cursor')?.outcome).toBe('installed');
+		});
+
+		it('outcome is "already_configured" for a pre-seeded client', async () => {
+			await seedState(['cursor']);
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+				flags_json: true,
+			});
+
+			const clients = parsedJsonOutput().clients as {
+				client: string;
+				outcome: string;
+			}[];
+			expect(clients.find((c) => c.client === 'cursor')?.outcome).toBe('already_configured');
+		});
+
+		it('"reason" field is NOT present in JSON output', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+				flags_json: true,
+			});
+
+			const clients = parsedJsonOutput().clients as Record<string, unknown>[];
+			for (const entry of clients) {
+				expect(entry).not.toHaveProperty('reason');
+			}
+		});
+
+		it('no JSON written to stdout when --json is not passed', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const jsonLine = logMessages.log.find((m) => m.startsWith('{'));
+			expect(jsonLine).toBeUndefined();
+		});
+
+		it('candidate order is preserved in JSON output (auto-detected order)', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			// Detect cursor via home path AND kiro via home path — cursor comes first
+			await mkdir(joinPath('.cursor'), { recursive: true });
+			await writeFile(joinPath('.cursor', 'mcp.json'), '{}', 'utf-8');
+			await mkdir(joinPath('.kiro'), { recursive: true });
+
+			await testRunCommand(AgentSetupCommand, {
+				flags_yes: true,
+				flags_json: true,
+			});
+
+			const clients = parsedJsonOutput().clients as { client: string }[];
+			const cursorIdx = clients.findIndex((c) => c.client === 'cursor');
+			const kiroIdx = clients.findIndex((c) => c.client === 'kiro');
+			if (cursorIdx >= 0 && kiroIdx >= 0) {
+				// cursor is listed before kiro in SUPPORTED_CLIENTS, so it should appear first
+				expect(cursorIdx).toBeLessThan(kiroIdx);
+			}
+		});
+	});
+
+	// ── Security ─────────────────────────────────────────────────────────────
+
+	describe('security', () => {
+		it('state file does not contain the API token', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const raw = await readFile((await import('../../../../src/lib/consts.js')).AGENT_STATE_FILE_PATH(), 'utf-8');
+			expect(raw).not.toContain(TEST_TOKEN);
+			expect(raw).not.toMatch(/Bearer /i);
+		});
+
+		it('state file is located inside GLOBAL_CONFIGS_FOLDER (not arbitrary path)', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const { AGENT_STATE_FILE_PATH, GLOBAL_CONFIGS_FOLDER } = await import('../../../../src/lib/consts.js');
+			expect(AGENT_STATE_FILE_PATH()).toContain(GLOBAL_CONFIGS_FOLDER());
+		});
+	});
+
+	// ── Error handling ────────────────────────────────────────────────────────
+
+	describe('error handling', () => {
+		it('handler failure (binary not found) is reported but does not crash the command', async () => {
+			// claude-code needs the `claude` binary. With PATH='', it won't be found.
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'claude-code',
+				flags_yes: true,
+			});
+
+			// Command exits non-zero from the handler, but doesn't throw unhandled
+			const stderr = logMessages.error.join('\n');
+			expect(stderr).toMatch(/'claude' CLI was not found on PATH|Failed to configure/i);
+		});
+
+		it('failed client is NOT written to the state file', async () => {
+			vitest.stubEnv('APIFY_TOKEN', TEST_TOKEN);
+			// claude-code fails (no binary).
+			await testRunCommand(AgentSetupCommand, {
+				flags_client: 'claude-code',
+				flags_yes: true,
+			});
+
+			const state = await readAgentState();
+			expect(state).toBeNull(); // nothing installed → no state written
+		});
+	});
+});
diff --git a/test/local/lib/agent/catalog.test.ts b/test/local/lib/agent/catalog.test.ts
new file mode 100644
index 000000000..285728e7a
--- /dev/null
+++ b/test/local/lib/agent/catalog.test.ts
@@ -0,0 +1,110 @@
+import {
+	buildSetupMcpUrl,
+	compareTiers,
+	getCatalog,
+	getClientEntry,
+	isKnownTier,
+} from '../../../../src/lib/agent/catalog.js';
+import { SUPPORTED_CLIENTS } from '../../../../src/lib/mcp/clients.js';
+
+describe('agent/catalog', () => {
+	describe('getCatalog()', () => {
+		it('returns an object with version, mcpUrl, skillsRepo, clients', () => {
+			const cat = getCatalog();
+			expect(cat).toHaveProperty('version');
+			expect(cat).toHaveProperty('mcpUrl');
+			expect(cat).toHaveProperty('skillsRepo');
+			expect(cat).toHaveProperty('clients');
+		});
+
+		it('mcpUrl is the Apify MCP base URL', () => {
+			expect(getCatalog().mcpUrl).toBe('https://mcp.apify.com');
+		});
+	});
+
+	describe('getClientEntry()', () => {
+		it('"claude-code" returns { maxTier: "mcp", plugin: null }', () => {
+			expect(getClientEntry('claude-code')).toEqual({
+				maxTier: 'mcp',
+				plugin: null,
+			});
+		});
+
+		it('"vscode" returns an object with a maxTier property', () => {
+			const entry = getClientEntry('vscode');
+			expect(entry).toBeDefined();
+			expect(entry).toHaveProperty('maxTier');
+		});
+
+		it('"unknown-xyz-client" returns undefined without throwing', () => {
+			expect(() => getClientEntry('unknown-xyz-client')).not.toThrow();
+			expect(getClientEntry('unknown-xyz-client')).toBeUndefined();
+		});
+	});
+
+	describe('compareTiers()', () => {
+		it('"plugin" vs "mcp" is negative (plugin is preferred)', () => {
+			expect(compareTiers('plugin', 'mcp')).toBeLessThan(0);
+		});
+
+		it('"mcp" vs "mcp" is 0', () => {
+			expect(compareTiers('mcp', 'mcp')).toBe(0);
+		});
+
+		it('"manual" vs "plugin" is positive', () => {
+			expect(compareTiers('manual', 'plugin')).toBeGreaterThan(0);
+		});
+	});
+
+	describe('buildSetupMcpUrl()', () => {
+		it('returns a URL containing client=apify-cli', () => {
+			expect(buildSetupMcpUrl()).toContain('client=apify-cli');
+		});
+
+		it('preserves existing query params from the base URL', () => {
+			const result = buildSetupMcpUrl('https://mcp.apify.com?tools=foo');
+			expect(result).toContain('client=apify-cli');
+			expect(result).toContain('tools=foo');
+		});
+
+		it('does not duplicate client= when already present in the base URL', () => {
+			const first = buildSetupMcpUrl();
+			const second = buildSetupMcpUrl(first);
+			expect(second).toBe(first);
+		});
+	});
+
+	describe('isKnownTier()', () => {
+		it('returns true for every value in TIER_ORDER', () => {
+			expect(isKnownTier('plugin')).toBe(true);
+			expect(isKnownTier('skills+mcp')).toBe(true);
+			expect(isKnownTier('mcp')).toBe(true);
+			expect(isKnownTier('manual')).toBe(true);
+		});
+
+		it('returns false for "__proto__"', () => {
+			expect(isKnownTier('__proto__')).toBe(false);
+		});
+
+		it('returns false for "constructor"', () => {
+			expect(isKnownTier('constructor')).toBe(false);
+		});
+
+		it('returns false for null', () => {
+			expect(isKnownTier(null)).toBe(false);
+		});
+
+		it('returns false for undefined', () => {
+			expect(isKnownTier(undefined)).toBe(false);
+		});
+	});
+
+	describe('catalog integrity', () => {
+		it('every client key in the catalog is present in SUPPORTED_CLIENTS (drift detection)', () => {
+			const catalogKeys = Object.keys(getCatalog().clients);
+			for (const key of catalogKeys) {
+				expect(SUPPORTED_CLIENTS).toContain(key);
+			}
+		});
+	});
+});
diff --git a/test/local/lib/agent/detection.test.ts b/test/local/lib/agent/detection.test.ts
new file mode 100644
index 000000000..1d82af6fc
--- /dev/null
+++ b/test/local/lib/agent/detection.test.ts
@@ -0,0 +1,175 @@
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { detectClients } from '../../../../src/lib/agent/detection.js';
+import { useTempPath } from '../../../__setup__/hooks/useTempPath.js';
+
+const { tmpPath, joinPath, beforeAllCalls, afterAllCalls } = useTempPath('agent-detection');
+
+beforeAll(beforeAllCalls);
+afterAll(afterAllCalls);
+
+beforeEach(async () => {
+	// Wipe state between tests so home-path checks start from a clean directory.
+	await rm(tmpPath, { recursive: true, force: true });
+	await mkdir(tmpPath, { recursive: true });
+	// Redirect ~ so existsSync checks land in the isolated tmpPath.
+	vitest.stubEnv('HOME', tmpPath);
+	// Clear PATH so which() never finds a real binary on the developer's machine.
+	vitest.stubEnv('PATH', '');
+});
+
+afterEach(() => {
+	vitest.unstubAllEnvs();
+});
+
+describe('agent/detection — detectClients()', () => {
+	it('returns [] when no env vars are set, PATH is empty, and ~ is empty', async () => {
+		expect(await detectClients()).toEqual([]);
+	});
+
+	// ── Env-var detection ────────────────────────────────────────────────────
+
+	describe('env-var detection', () => {
+		it('CLAUDECODE → claude-code detected', async () => {
+			vitest.stubEnv('CLAUDECODE', '1');
+			expect(await detectClients()).toContain('claude-code');
+		});
+
+		it('CLAUDE_CODE_ENTRYPOINT → claude-code detected', async () => {
+			vitest.stubEnv('CLAUDE_CODE_ENTRYPOINT', 'cli');
+			expect(await detectClients()).toContain('claude-code');
+		});
+
+		it('CURSOR_AGENT → cursor detected', async () => {
+			vitest.stubEnv('CURSOR_AGENT', '1');
+			expect(await detectClients()).toContain('cursor');
+		});
+
+		it('CODEX_SANDBOX → codex detected', async () => {
+			vitest.stubEnv('CODEX_SANDBOX', '1');
+			expect(await detectClients()).toContain('codex');
+		});
+
+		it('CODEX_THREAD_ID → codex detected', async () => {
+			vitest.stubEnv('CODEX_THREAD_ID', 'abc123');
+			expect(await detectClients()).toContain('codex');
+		});
+
+		it('OPENCLAW_SHELL → antigravity detected', async () => {
+			vitest.stubEnv('OPENCLAW_SHELL', '1');
+			expect(await detectClients()).toContain('antigravity');
+		});
+
+		it('CLINE_ACTIVE → NOT detected (cline is not a supported catalog client)', async () => {
+			vitest.stubEnv('CLINE_ACTIVE', '1');
+			expect(await detectClients()).toEqual([]);
+		});
+
+		it('GEMINI_CLI → NOT detected (no catalog client maps to gemini_cli)', async () => {
+			vitest.stubEnv('GEMINI_CLI', '1');
+			expect(await detectClients()).toEqual([]);
+		});
+
+		it('OPENCODE → NOT detected (open_code not in catalog)', async () => {
+			vitest.stubEnv('OPENCODE', '1');
+			expect(await detectClients()).toEqual([]);
+		});
+
+		it('multiple env vars → multiple clients detected', async () => {
+			vitest.stubEnv('CLAUDECODE', '1');
+			vitest.stubEnv('CURSOR_AGENT', '1');
+			vitest.stubEnv('CODEX_THREAD_ID', 'x');
+			const detected = await detectClients();
+			expect(detected).toContain('claude-code');
+			expect(detected).toContain('cursor');
+			expect(detected).toContain('codex');
+		});
+	});
+
+	// ── Home-path detection ──────────────────────────────────────────────────
+
+	describe('home-path detection', () => {
+		it('~/.claude exists → claude-code detected', async () => {
+			await mkdir(joinPath('.claude'), { recursive: true });
+			expect(await detectClients()).toContain('claude-code');
+		});
+
+		it('~/.cursor/mcp.json exists → cursor detected', async () => {
+			await mkdir(joinPath('.cursor'), { recursive: true });
+			await writeFile(joinPath('.cursor', 'mcp.json'), '{}', 'utf-8');
+			expect(await detectClients()).toContain('cursor');
+		});
+
+		it('~/.cursor dir without mcp.json → cursor NOT detected', async () => {
+			// Detection requires the mcp.json file specifically, not just the .cursor dir.
+			await mkdir(joinPath('.cursor'), { recursive: true });
+			expect(await detectClients()).not.toContain('cursor');
+		});
+
+		it('~/.vscode exists → vscode detected', async () => {
+			await mkdir(joinPath('.vscode'), { recursive: true });
+			expect(await detectClients()).toContain('vscode');
+		});
+
+		it('~/.vscode-insiders exists → vscode-insiders detected', async () => {
+			await mkdir(joinPath('.vscode-insiders'), { recursive: true });
+			expect(await detectClients()).toContain('vscode-insiders');
+		});
+
+		it('~/.kiro exists → kiro detected', async () => {
+			await mkdir(joinPath('.kiro'), { recursive: true });
+			expect(await detectClients()).toContain('kiro');
+		});
+
+		it('~/.gemini/antigravity exists → antigravity detected', async () => {
+			await mkdir(joinPath('.gemini', 'antigravity'), { recursive: true });
+			expect(await detectClients()).toContain('antigravity');
+		});
+
+		it('~/.gemini exists without antigravity subdir → antigravity NOT detected', async () => {
+			await mkdir(joinPath('.gemini'), { recursive: true });
+			expect(await detectClients()).not.toContain('antigravity');
+		});
+
+		it('multiple home paths → multiple clients detected simultaneously', async () => {
+			await mkdir(joinPath('.claude'), { recursive: true });
+			await mkdir(joinPath('.kiro'), { recursive: true });
+			const detected = await detectClients();
+			expect(detected).toContain('claude-code');
+			expect(detected).toContain('kiro');
+		});
+	});
+
+	// ── Ordering and deduplication ────────────────────────────────────────────
+
+	describe('ordering', () => {
+		it('env-detected client appears before home-path-only client', async () => {
+			vitest.stubEnv('CLAUDECODE', '1'); // claude-code via env
+			// cursor detected via home path only
+			await mkdir(joinPath('.cursor'), { recursive: true });
+			await writeFile(joinPath('.cursor', 'mcp.json'), '{}', 'utf-8');
+
+			const detected = await detectClients();
+			expect(detected.indexOf('claude-code')).toBeLessThan(detected.indexOf('cursor'));
+		});
+
+		it('a client detected by both env and home path appears exactly once', async () => {
+			vitest.stubEnv('CURSOR_AGENT', '1');
+			await mkdir(joinPath('.cursor'), { recursive: true });
+			await writeFile(joinPath('.cursor', 'mcp.json'), '{}', 'utf-8');
+
+			const detected = await detectClients();
+			expect(detected.filter((c) => c === 'cursor')).toHaveLength(1);
+		});
+
+		it('result contains no duplicate entries across any combination of signals', async () => {
+			vitest.stubEnv('CLAUDECODE', '1');
+			vitest.stubEnv('CLAUDE_CODE_ENTRYPOINT', 'cli'); // second signal for same client
+			await mkdir(joinPath('.claude'), { recursive: true }); // third signal for same client
+
+			const detected = await detectClients();
+			expect(detected.filter((c) => c === 'claude-code')).toHaveLength(1);
+		});
+	});
+});
diff --git a/test/local/lib/agent/state.test.ts b/test/local/lib/agent/state.test.ts
new file mode 100644
index 000000000..7b8281037
--- /dev/null
+++ b/test/local/lib/agent/state.test.ts
@@ -0,0 +1,178 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import process from 'node:process';
+
+import {
+	isClientConfigured,
+	readAgentState,
+	writeAgentState,
+	type AgentState,
+} from '../../../../src/lib/agent/state.js';
+import { AGENT_STATE_FILE_PATH } from '../../../../src/lib/consts.js';
+import { useAuthSetup } from '../../../__setup__/hooks/useAuthSetup.js';
+
+// useAuthSetup redirects GLOBAL_CONFIGS_FOLDER (and therefore AGENT_STATE_FILE_PATH) to
+// a per-test isolated path under ~/.apify/<random>/, keeping state tests hermetic.
+useAuthSetup();
+
+const FIXED_TS = '2026-01-01T00:00:00.000Z';
+
+describe('agent/state', () => {
+	// ── readAgentState() ─────────────────────────────────────────────────────
+
+	describe('readAgentState()', () => {
+		it('returns null when the state file does not exist', async () => {
+			expect(await readAgentState()).toBeNull();
+		});
+
+		it('returns null on malformed JSON without throwing', async () => {
+			const { mkdir, writeFile } = await import('node:fs/promises');
+			const { dirname } = await import('node:path');
+			const path = AGENT_STATE_FILE_PATH();
+			await mkdir(dirname(path), { recursive: true });
+			await writeFile(path, '{ invalid json ::: }', 'utf-8');
+
+			expect(await readAgentState()).toBeNull();
+		});
+
+		it('returns null on empty file without throwing', async () => {
+			const { mkdir, writeFile } = await import('node:fs/promises');
+			const { dirname } = await import('node:path');
+			const path = AGENT_STATE_FILE_PATH();
+			await mkdir(dirname(path), { recursive: true });
+			await writeFile(path, '', 'utf-8');
+
+			expect(await readAgentState()).toBeNull();
+		});
+	});
+
+	// ── writeAgentState() round-trip ──────────────────────────────────────────
+
+	describe('writeAgentState()', () => {
+		it('round-trips through readAgentState() with no loss', async () => {
+			const state: AgentState = {
+				installedAt: FIXED_TS,
+				clients: [
+					{
+						client: 'claude-code',
+						tier: 'mcp',
+						installedAt: FIXED_TS,
+					},
+					{ client: 'cursor', tier: 'mcp', installedAt: FIXED_TS },
+				],
+			};
+			await writeAgentState(state);
+			expect(await readAgentState()).toEqual(state);
+		});
+
+		it('writes the spec-compliant JSON structure to disk', async () => {
+			const state: AgentState = {
+				installedAt: FIXED_TS,
+				clients: [{ client: 'cursor', tier: 'mcp', installedAt: FIXED_TS }],
+			};
+
+			await writeAgentState(state);
+
+			const raw = JSON.parse(await readFile(AGENT_STATE_FILE_PATH(), 'utf-8')) as unknown;
+			expect(raw).toEqual({
+				installedAt: FIXED_TS,
+				clients: [{ client: 'cursor', tier: 'mcp', installedAt: FIXED_TS }],
+			});
+		});
+
+		it('state file ends with a newline', async () => {
+			await writeAgentState({ installedAt: FIXED_TS, clients: [] });
+			const raw = await readFile(AGENT_STATE_FILE_PATH(), 'utf-8');
+			expect(raw.endsWith('\n')).toBe(true);
+		});
+
+		it('creates parent directories when they do not exist', async () => {
+			// useAuthSetup redirects to a new path per test — no directory yet.
+			await expect(writeAgentState({ installedAt: FIXED_TS, clients: [] })).resolves.toBeUndefined();
+			expect(existsSync(AGENT_STATE_FILE_PATH())).toBe(true);
+		});
+
+		it('leaves no .tmp file behind after a successful write', async () => {
+			await writeAgentState({ installedAt: FIXED_TS, clients: [] });
+			const tmpPath = `${AGENT_STATE_FILE_PATH()}.${process.pid}.tmp`;
+			expect(existsSync(tmpPath)).toBe(false);
+		});
+
+		it('overwrites an existing state file on re-write', async () => {
+			const v1: AgentState = {
+				installedAt: FIXED_TS,
+				clients: [{ client: 'cursor', tier: 'mcp', installedAt: FIXED_TS }],
+			};
+			const v2: AgentState = {
+				installedAt: FIXED_TS,
+				clients: [
+					{ client: 'cursor', tier: 'mcp', installedAt: FIXED_TS },
+					{ client: 'kiro', tier: 'mcp', installedAt: FIXED_TS },
+				],
+			};
+
+			await writeAgentState(v1);
+			await writeAgentState(v2);
+
+			expect(await readAgentState()).toEqual(v2);
+		});
+
+		it('state file does NOT contain API tokens (security)', async () => {
+			const state: AgentState = {
+				installedAt: FIXED_TS,
+				clients: [{ client: 'cursor', tier: 'mcp', installedAt: FIXED_TS }],
+			};
+			await writeAgentState(state);
+
+			const raw = await readFile(AGENT_STATE_FILE_PATH(), 'utf-8');
+			// There should be no token-like value (apify_api_ prefix) in the state file.
+			expect(raw).not.toMatch(/apify_api_/i);
+			expect(raw).not.toMatch(/Bearer /i);
+		});
+	});
+
+	// ── isClientConfigured() ─────────────────────────────────────────────────
+
+	describe('isClientConfigured()', () => {
+		it('returns true when the client is present in the clients array', () => {
+			const state: AgentState = {
+				installedAt: FIXED_TS,
+				clients: [
+					{
+						client: 'claude-code',
+						tier: 'mcp',
+						installedAt: FIXED_TS,
+					},
+				],
+			};
+			expect(isClientConfigured(state, 'claude-code')).toBe(true);
+		});
+
+		it('returns false when the client is absent from the clients array', () => {
+			const state: AgentState = {
+				installedAt: FIXED_TS,
+				clients: [{ client: 'cursor', tier: 'mcp', installedAt: FIXED_TS }],
+			};
+			expect(isClientConfigured(state, 'claude-code')).toBe(false);
+		});
+
+		it('returns false for an empty clients array', () => {
+			expect(isClientConfigured({ installedAt: FIXED_TS, clients: [] }, 'cursor')).toBe(false);
+		});
+
+		it('is case-sensitive (client keys are always lower-kebab)', () => {
+			const state: AgentState = {
+				installedAt: FIXED_TS,
+				clients: [
+					{
+						client: 'claude-code',
+						tier: 'mcp',
+						installedAt: FIXED_TS,
+					},
+				],
+			};
+			expect(isClientConfigured(state, 'Claude-Code')).toBe(false);
+			expect(isClientConfigured(state, 'CLAUDE-CODE')).toBe(false);
+		});
+	});
+});

From 8f6ced15454e2193fede2344d495e16985dc188a Mon Sep 17 00:00:00 2001
From: kuntal1461 <kuntal.1461@gmail.com>
Date: Mon, 5 Oct 2026 22:23:00 +0530
Subject: [PATCH 3/3] feat: add apify agent status and agent uninstall commands
 (P1)

Implements the two remaining agent commands:
- apify agent status: reads agent-state.json, shows configured clients
  with tier and install date; supports --client filter and --json output
- apify agent uninstall: removes MCP config per client, updates state
  file; supports --client, --yes, --json; confirms before removing

New infrastructure:
- removeServerEntry() in file-config.ts: JSONC-safe atomic removal of
  a key from any mcp.json (symmetric to mergeServerEntry)
- Uninstall handlers for all 7 clients (file-based and CLI-based)
- isSupportedClient guard on state-sourced targets
- writeAgentState wrapped in try/catch for disk-full/permission errors
- Partial-failure contract: failed clients kept in state, RunFailed exit

45 tests across status (18) and uninstall (27), including security proofs,
partial-failure multi-client coverage, and empty-state edge cases.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/commands/agent/_index.ts                |   4 +-
 src/commands/agent/status.ts                |  88 ++++
 src/commands/agent/uninstall.ts             | 208 ++++++++
 src/lib/mcp/clients.ts                      | 172 ++++++-
 src/lib/mcp/file-config.ts                  |  47 ++
 test/local/commands/agent/status.test.ts    | 244 +++++++++
 test/local/commands/agent/uninstall.test.ts | 532 ++++++++++++++++++++
 7 files changed, 1287 insertions(+), 8 deletions(-)
 create mode 100644 src/commands/agent/status.ts
 create mode 100644 src/commands/agent/uninstall.ts
 create mode 100644 test/local/commands/agent/status.test.ts
 create mode 100644 test/local/commands/agent/uninstall.test.ts

diff --git a/src/commands/agent/_index.ts b/src/commands/agent/_index.ts
index bfd693ccf..0f9929467 100644
--- a/src/commands/agent/_index.ts
+++ b/src/commands/agent/_index.ts
@@ -1,5 +1,7 @@
 import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
 import { AgentSetupCommand } from './setup.js';
+import { AgentStatusCommand } from './status.js';
+import { AgentUninstallCommand } from './uninstall.js';
 
 export class AgentIndexCommand extends ApifyCommand<typeof AgentIndexCommand> {
 	static override name = 'agent' as const;
@@ -11,7 +13,7 @@ export class AgentIndexCommand extends ApifyCommand<typeof AgentIndexCommand> {
 
 	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#apify-agent';
 
-	static override subcommands = [AgentSetupCommand];
+	static override subcommands = [AgentSetupCommand, AgentStatusCommand, AgentUninstallCommand];
 
 	async run() {
 		this.printHelp();
diff --git a/src/commands/agent/status.ts b/src/commands/agent/status.ts
new file mode 100644
index 000000000..bb0ecb713
--- /dev/null
+++ b/src/commands/agent/status.ts
@@ -0,0 +1,88 @@
+import process from 'node:process';
+
+import chalk from 'chalk';
+
+import { readAgentState } from '../../lib/agent/state.js';
+import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
+import { Flags } from '../../lib/command-framework/flags.js';
+import { CommandExitCodes } from '../../lib/consts.js';
+import { isSupportedClient, SUPPORTED_CLIENTS } from '../../lib/mcp/clients.js';
+import { error, simpleLog } from '../../lib/outputs.js';
+import { printJsonToStdout } from '../../lib/utils.js';
+
+export class AgentStatusCommand extends ApifyCommand<typeof AgentStatusCommand> {
+	static override name = 'status' as const;
+
+	static override description =
+		'Show which AI coding agents have been configured by `apify agent setup`, along with their tier and install date.';
+
+	static override group = 'Agent';
+
+	static override enableJsonFlag = true;
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#apify-agent-status';
+
+	static override examples = [
+		{
+			description: 'Show all configured agents.',
+			command: 'apify agent status',
+		},
+		{
+			description: 'Check whether Cursor is configured.',
+			command: 'apify agent status --client cursor',
+		},
+		{
+			description: 'Machine-readable output.',
+			command: 'apify agent status --json',
+		},
+	];
+
+	static override flags = {
+		client: Flags.string({
+			description: `Show status for a specific client only. One of: ${SUPPORTED_CLIENTS.join(', ')}.`,
+		}),
+	};
+
+	async run() {
+		const { client: clientFlag, json } = this.flags;
+
+		if (clientFlag && !isSupportedClient(clientFlag)) {
+			error({
+				message: `Unknown client '${clientFlag}'. Supported: ${SUPPORTED_CLIENTS.join(', ')}.`,
+			});
+			process.exitCode = CommandExitCodes.InvalidInput;
+			return;
+		}
+
+		const state = await readAgentState();
+
+		if (!state || state.clients.length === 0) {
+			simpleLog({
+				message: 'No agents configured. Run `apify agent setup` to get started.',
+			});
+			if (json) printJsonToStdout({ clients: [] });
+			return;
+		}
+
+		const clients = clientFlag !== undefined ? state.clients.filter((r) => r.client === clientFlag) : state.clients;
+
+		if (clients.length === 0) {
+			simpleLog({
+				message: `'${clientFlag}' is not configured. Run \`apify agent setup --client ${clientFlag}\` to configure it.`,
+			});
+			if (json) printJsonToStdout({ clients: [] });
+			return;
+		}
+
+		const lines = clients.map(
+			(r) =>
+				`  ${chalk.bold(r.client.padEnd(18))}  ${chalk.cyan(`[${r.tier} tier]`)}  configured ${new Date(r.installedAt).toLocaleDateString()}`,
+		);
+
+		simpleLog({
+			message: [`\nConfigured agents (${clients.length}):`, ...lines, ''].join('\n'),
+		});
+
+		if (json) printJsonToStdout({ clients });
+	}
+}
diff --git a/src/commands/agent/uninstall.ts b/src/commands/agent/uninstall.ts
new file mode 100644
index 000000000..d813286b0
--- /dev/null
+++ b/src/commands/agent/uninstall.ts
@@ -0,0 +1,208 @@
+import process from 'node:process';
+
+import chalk from 'chalk';
+
+import { isClientConfigured, readAgentState, writeAgentState } from '../../lib/agent/state.js';
+import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
+import { Flags, YesFlag } from '../../lib/command-framework/flags.js';
+import { CommandExitCodes } from '../../lib/consts.js';
+import { useYesNoConfirm } from '../../lib/hooks/user-confirmations/useYesNoConfirm.js';
+import {
+	getClientUninstallHandler,
+	isSupportedClient,
+	type ClientName,
+	SUPPORTED_CLIENTS,
+} from '../../lib/mcp/clients.js';
+import { error, simpleLog } from '../../lib/outputs.js';
+import { printJsonToStdout } from '../../lib/utils.js';
+
+type UninstallOutcome = 'uninstalled' | 'not_configured' | 'failed';
+
+interface UninstallResult {
+	client: string;
+	outcome: UninstallOutcome;
+	reason?: string;
+}
+
+export class AgentUninstallCommand extends ApifyCommand<typeof AgentUninstallCommand> {
+	static override name = 'uninstall' as const;
+
+	static override description =
+		'Remove Apify MCP configuration from AI coding agents previously set up by `apify agent setup`. Updates the local state file.';
+
+	static override group = 'Agent';
+
+	static override interactive = true;
+
+	static override interactiveNote =
+		'Prompts once before removing. Pass --yes to skip. Pass --non-interactive to suppress all prompts.';
+
+	static override enableJsonFlag = true;
+
+	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#apify-agent-uninstall';
+
+	static override examples = [
+		{
+			description: 'Uninstall all configured agents (prompts for confirmation).',
+			command: 'apify agent uninstall',
+		},
+		{
+			description: 'Uninstall Cursor without a confirmation prompt.',
+			command: 'apify agent uninstall --client cursor --yes',
+		},
+		{
+			description: 'Machine-readable uninstall from a CI script.',
+			command: 'apify agent uninstall --yes --json',
+		},
+	];
+
+	static override flags = {
+		...YesFlag('Skip the confirmation prompt and remove immediately.'),
+		client: Flags.string({
+			description: `Target a specific client. One of: ${SUPPORTED_CLIENTS.join(', ')}. Omit to uninstall all configured clients.`,
+		}),
+	};
+
+	async run() {
+		const { yes, client: clientFlag, json } = this.flags;
+
+		if (clientFlag && !isSupportedClient(clientFlag)) {
+			error({
+				message: `Unknown client '${clientFlag}'. Supported: ${SUPPORTED_CLIENTS.join(', ')}.`,
+			});
+			process.exitCode = CommandExitCodes.InvalidInput;
+			return;
+		}
+
+		// ── Step 1: Determine targets from state file ────────────────────────
+		const state = await readAgentState();
+
+		let targets: ClientName[];
+
+		if (clientFlag) {
+			const typedClient = clientFlag as ClientName;
+			if (!state || !isClientConfigured(state, typedClient)) {
+				simpleLog({
+					message: `'${clientFlag}' is not configured. Nothing to uninstall.`,
+				});
+				if (json)
+					printJsonToStdout({
+						clients: [{ client: clientFlag, outcome: 'not_configured' }],
+					});
+				return;
+			}
+			targets = [typedClient];
+		} else {
+			if (!state || state.clients.length === 0) {
+				simpleLog({
+					message: 'No agents configured. Nothing to uninstall.',
+				});
+				if (json) printJsonToStdout({ clients: [] });
+				return;
+			}
+			targets = state.clients
+				.filter((r) => {
+					if (!isSupportedClient(r.client)) {
+						error({
+							message: `Skipping unknown client '${r.client}' found in state file.`,
+						});
+						return false;
+					}
+					return true;
+				})
+				.map((r) => r.client as ClientName);
+
+			if (targets.length === 0) {
+				simpleLog({
+					message: 'No agents configured. Nothing to uninstall.',
+				});
+				if (json) printJsonToStdout({ clients: [] });
+				return;
+			}
+		}
+
+		// ── Step 2: Show plan, confirm ────────────────────────────────────────
+		const planLines = targets.map((c) => `  ${chalk.bold(c)}`);
+		simpleLog({
+			message: [
+				`\nWill remove Apify MCP configuration for ${targets.length} agent${targets.length === 1 ? '' : 's'}:`,
+				...planLines,
+			].join('\n'),
+		});
+
+		const confirmed = await useYesNoConfirm({
+			message: 'Remove the configuration above?',
+			default: false,
+			providedConfirmFromStdin: yes || undefined,
+			errorMessageForStdin: 'Re-run with --yes to skip this prompt.',
+		});
+
+		if (!confirmed) {
+			simpleLog({ message: 'Aborted. No changes were made.' });
+			if (json) printJsonToStdout({ clients: [] });
+			return;
+		}
+
+		// ── Step 3: Apply per client ─────────────────────────────────────────
+		const results: UninstallResult[] = [];
+		let anyFailed = false;
+
+		for (const client of targets) {
+			process.exitCode = undefined;
+			try {
+				await getClientUninstallHandler(client)();
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				error({
+					message: `Failed to uninstall '${client}': ${message}`,
+				});
+				results.push({ client, outcome: 'failed', reason: message });
+				anyFailed = true;
+				process.exitCode = undefined;
+				continue;
+			}
+
+			if (process.exitCode !== undefined) {
+				results.push({
+					client,
+					outcome: 'failed',
+					reason: `exit ${String(process.exitCode)}`,
+				});
+				anyFailed = true;
+				process.exitCode = undefined;
+			} else {
+				results.push({ client, outcome: 'uninstalled' });
+			}
+		}
+
+		if (anyFailed) {
+			process.exitCode = CommandExitCodes.RunFailed;
+		}
+
+		// ── Step 4: Update state file ────────────────────────────────────────
+		const uninstalledClients = new Set(results.filter((r) => r.outcome === 'uninstalled').map((r) => r.client));
+
+		if (uninstalledClients.size > 0 && state) {
+			const newState = {
+				...state,
+				clients: state.clients.filter((r) => !uninstalledClients.has(r.client)),
+			};
+			try {
+				await writeAgentState(newState);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				error({
+					message: `Failed to update state file: ${message}. Re-run to sync state.`,
+				});
+				if (!anyFailed) process.exitCode = CommandExitCodes.RunFailed;
+			}
+		}
+
+		// ── Step 5: Machine-readable output ─────────────────────────────────
+		if (json) {
+			printJsonToStdout({
+				clients: results.map(({ reason: _reason, ...rest }) => rest),
+			});
+		}
+	}
+}
diff --git a/src/lib/mcp/clients.ts b/src/lib/mcp/clients.ts
index fa9a600f6..d6f850929 100644
--- a/src/lib/mcp/clients.ts
+++ b/src/lib/mcp/clients.ts
@@ -8,7 +8,7 @@ import which from 'which';
 import { CommandExitCodes } from '../consts.js';
 import { error, run, simpleLog, success } from '../outputs.js';
 import { tildify, userHomeDir } from '../utils.js';
-import { mergeServerEntry } from './file-config.js';
+import { mergeServerEntry, removeServerEntry } from './file-config.js';
 import { maskSecret, maskToken } from './url.js';
 
 const SERVER_KEY = 'apify';
@@ -31,7 +31,9 @@ interface InstallResult {
 }
 
 function printResult(result: InstallResult): void {
-	success({ message: `Apify MCP server configured for ${result.clientLabel}.` });
+	success({
+		message: `Apify MCP server configured for ${result.clientLabel}.`,
+	});
 
 	const lines = [
 		'',
@@ -92,7 +94,9 @@ async function runCliInstall({
 	} catch (err) {
 		const childStderr = isExecaError(err) ? String(err.stderr ?? '').trim() : '';
 		const reason = childStderr ? `${describeExecaError(err, binary)}\n${childStderr}` : describeExecaError(err, binary);
-		error({ message: maskSecret(`Failed to add the MCP server via ${clientLabel}: ${reason}`, token) });
+		error({
+			message: maskSecret(`Failed to add the MCP server via ${clientLabel}: ${reason}`, token),
+		});
 		process.exitCode = CommandExitCodes.RunFailed;
 		return false;
 	}
@@ -112,7 +116,9 @@ function fileClient({
 	return async ({ url, token, yes }) => {
 		const home = userHomeDir();
 		if (!home) {
-			error({ message: 'User home directory could not be determined. Set the HOME environment variable and re-run.' });
+			error({
+				message: 'User home directory could not be determined. Set the HOME environment variable and re-run.',
+			});
 			process.exitCode = CommandExitCodes.InvalidInput;
 			return;
 		}
@@ -172,7 +178,12 @@ const claudeCodeHandler: ClientHandler = async ({ url, token }) => {
 function vscodeHandler(binary: string, clientLabel: string): ClientHandler {
 	return async ({ url, token }) => {
 		const serverJson = (auth: string) =>
-			JSON.stringify({ name: SERVER_KEY, type: 'http', url, headers: { Authorization: auth } });
+			JSON.stringify({
+				name: SERVER_KEY,
+				type: 'http',
+				url,
+				headers: { Authorization: auth },
+			});
 
 		const ok = await runCliInstall({
 			binary,
@@ -195,7 +206,9 @@ function vscodeHandler(binary: string, clientLabel: string): ClientHandler {
 const codexHandler: ClientHandler = async ({ url }) => {
 	const home = userHomeDir();
 	if (!home) {
-		error({ message: 'User home directory could not be determined. Set the HOME environment variable and re-run.' });
+		error({
+			message: 'User home directory could not be determined. Set the HOME environment variable and re-run.',
+		});
 		process.exitCode = CommandExitCodes.InvalidInput;
 		return;
 	}
@@ -238,7 +251,12 @@ const HANDLERS = {
 	kiro: fileClient({
 		label: 'Kiro',
 		segments: ['.kiro', 'settings', 'mcp.json'],
-		entry: (url, token) => ({ url, headers: bearer(token), disabled: false, autoApprove: [] as string[] }),
+		entry: (url, token) => ({
+			url,
+			headers: bearer(token),
+			disabled: false,
+			autoApprove: [] as string[],
+		}),
 	}),
 	antigravity: fileClient({
 		label: 'Antigravity',
@@ -266,3 +284,143 @@ export function clientNeedsToken(name: ClientName): boolean {
 export function getClientHandler(name: ClientName): ClientHandler {
 	return HANDLERS[name];
 }
+
+// ── Uninstall ────────────────────────────────────────────────────────────────
+
+type ClientUninstallHandler = () => Promise<void>;
+
+/**
+ * Shell out to a client CLI to remove the server. Same failure contract as runCliInstall:
+ * sets process.exitCode and returns false without throwing on binary-not-found or run failure.
+ */
+async function runCliUninstall({
+	binary,
+	clientLabel,
+	args,
+	maskedCommand,
+	missingMessage,
+}: {
+	binary: string;
+	clientLabel: string;
+	args: string[];
+	maskedCommand: string;
+	missingMessage: string;
+}): Promise<boolean> {
+	if (!(await which(binary, { nothrow: true }))) {
+		error({ message: missingMessage });
+		process.exitCode = CommandExitCodes.NotFound;
+		return false;
+	}
+
+	run({ message: maskedCommand });
+	try {
+		await execa(binary, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+	} catch (err) {
+		const childStderr = isExecaError(err) ? String(err.stderr ?? '').trim() : '';
+		const reason = childStderr ? `${describeExecaError(err, binary)}\n${childStderr}` : describeExecaError(err, binary);
+		error({
+			message: `Failed to remove MCP server via ${clientLabel}: ${reason}`,
+		});
+		process.exitCode = CommandExitCodes.RunFailed;
+		return false;
+	}
+	return true;
+}
+
+function fileClientUninstall({ label, segments }: { label: string; segments: string[] }): ClientUninstallHandler {
+	return async () => {
+		const home = userHomeDir();
+		if (!home) {
+			error({
+				message: 'User home directory could not be determined. Set the HOME environment variable and re-run.',
+			});
+			process.exitCode = CommandExitCodes.InvalidInput;
+			return;
+		}
+		const filePath = join(home, ...segments);
+		const removed = await removeServerEntry({
+			filePath,
+			topLevelKey: 'mcpServers',
+			entryKey: SERVER_KEY,
+		});
+		if (removed) {
+			success({
+				message: `Removed Apify MCP server from ${label} config (${tildify(filePath)}).`,
+			});
+		} else {
+			simpleLog({
+				message: `  No Apify MCP entry found in ${tildify(filePath)} — config already clean.`,
+			});
+		}
+	};
+}
+
+const claudeCodeUninstallHandler: ClientUninstallHandler = async () => {
+	const ok = await runCliUninstall({
+		binary: 'claude',
+		clientLabel: 'Claude Code',
+		args: ['mcp', 'remove', '--scope', 'user', SERVER_KEY],
+		maskedCommand: `claude mcp remove --scope user ${SERVER_KEY}`,
+		missingMessage: `The 'claude' CLI was not found on PATH. Remove manually:\n\n    claude mcp remove --scope user ${SERVER_KEY}`,
+	});
+	if (!ok) return;
+	success({ message: `Removed Apify MCP server from Claude Code.` });
+};
+
+function vscodeUninstallHandler(binary: string, clientLabel: string): ClientUninstallHandler {
+	return async () => {
+		const ok = await runCliUninstall({
+			binary,
+			clientLabel,
+			args: ['--remove-mcp', SERVER_KEY],
+			maskedCommand: `${binary} --remove-mcp ${SERVER_KEY}`,
+			missingMessage: `The '${binary}' CLI was not found on PATH. Remove manually:\n\n    ${binary} --remove-mcp ${SERVER_KEY}`,
+		});
+		if (!ok) return;
+		success({ message: `Removed Apify MCP server from ${clientLabel}.` });
+	};
+}
+
+const codexUninstallHandler: ClientUninstallHandler = async () => {
+	const home = userHomeDir();
+	if (!home) {
+		error({
+			message: 'User home directory could not be determined. Set the HOME environment variable and re-run.',
+		});
+		process.exitCode = CommandExitCodes.InvalidInput;
+		return;
+	}
+	const tomlPath = join(home, '.codex', 'config.toml');
+	const ok = await runCliUninstall({
+		binary: 'codex',
+		clientLabel: 'Codex CLI',
+		args: ['mcp', 'remove', SERVER_KEY],
+		maskedCommand: `codex mcp remove ${SERVER_KEY}`,
+		missingMessage: `The 'codex' CLI was not found on PATH. Remove the [mcp_servers.${SERVER_KEY}] block manually from ${tildify(tomlPath)}.`,
+	});
+	if (!ok) return;
+	success({ message: `Removed Apify MCP server from Codex CLI.` });
+};
+
+const UNINSTALL_HANDLERS: Record<ClientName, ClientUninstallHandler> = {
+	'claude-code': claudeCodeUninstallHandler,
+	cursor: fileClientUninstall({
+		label: 'Cursor',
+		segments: ['.cursor', 'mcp.json'],
+	}),
+	vscode: vscodeUninstallHandler('code', 'VS Code'),
+	'vscode-insiders': vscodeUninstallHandler('code-insiders', 'VS Code Insiders'),
+	codex: codexUninstallHandler,
+	kiro: fileClientUninstall({
+		label: 'Kiro',
+		segments: ['.kiro', 'settings', 'mcp.json'],
+	}),
+	antigravity: fileClientUninstall({
+		label: 'Antigravity',
+		segments: ['.gemini', 'antigravity', 'mcp_config.json'],
+	}),
+};
+
+export function getClientUninstallHandler(name: ClientName): ClientUninstallHandler {
+	return UNINSTALL_HANDLERS[name];
+}
diff --git a/src/lib/mcp/file-config.ts b/src/lib/mcp/file-config.ts
index c612f13c3..cc58c290f 100644
--- a/src/lib/mcp/file-config.ts
+++ b/src/lib/mcp/file-config.ts
@@ -104,3 +104,50 @@ export async function mergeServerEntry({
 	}
 	return true;
 }
+
+/**
+ * Remove one entry from a JSONC config file's top-level key.
+ * Returns true if the entry was found and removed, false if it was not present or the file did not exist.
+ * Preserves all other content (comments, indentation, unrelated keys) via jju.update.
+ */
+export async function removeServerEntry({
+	filePath,
+	topLevelKey,
+	entryKey,
+}: {
+	filePath: string;
+	topLevelKey: string;
+	entryKey: string;
+}): Promise<boolean> {
+	if (!existsSync(filePath)) return false;
+
+	const text = await readFile(filePath, 'utf-8');
+	if (!text.trim()) return false;
+
+	let document: Record<string, unknown>;
+	try {
+		document = jju.parse(text) as Record<string, unknown>;
+	} catch {
+		return false;
+	}
+
+	const topLevel = document[topLevelKey];
+	if (typeof topLevel !== 'object' || topLevel === null || Array.isArray(topLevel)) return false;
+
+	const topLevelObj = topLevel as Record<string, unknown>;
+	if (!Object.prototype.hasOwnProperty.call(topLevelObj, entryKey)) return false;
+
+	delete topLevelObj[entryKey];
+	document[topLevelKey] = topLevelObj;
+
+	const newText = jju.update(text, document);
+	const tmpPath = `${filePath}.${process.pid}.tmp`;
+	try {
+		await writeFile(tmpPath, newText, 'utf-8');
+		await rename(tmpPath, filePath);
+	} catch (err) {
+		await rm(tmpPath, { force: true });
+		throw err;
+	}
+	return true;
+}
diff --git a/test/local/commands/agent/status.test.ts b/test/local/commands/agent/status.test.ts
new file mode 100644
index 000000000..856884581
--- /dev/null
+++ b/test/local/commands/agent/status.test.ts
@@ -0,0 +1,244 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import process from 'node:process';
+
+vitest.mock('ci-info', async (importOriginal) => {
+	const original = await importOriginal<typeof import('ci-info')>();
+	return { ...original, isCI: true };
+});
+
+import { AgentStatusCommand } from '../../../../src/commands/agent/status.js';
+import { writeAgentState, type AgentState } from '../../../../src/lib/agent/state.js';
+import { testRunCommand } from '../../../../src/lib/command-framework/apify-command.js';
+import { CommandExitCodes } from '../../../../src/lib/consts.js';
+import { useAuthSetup } from '../../../__setup__/hooks/useAuthSetup.js';
+import { useConsoleSpy } from '../../../__setup__/hooks/useConsoleSpy.js';
+import { useTempPath } from '../../../__setup__/hooks/useTempPath.js';
+
+const { tmpPath, beforeAllCalls, afterAllCalls } = useTempPath('agent-status');
+
+useAuthSetup();
+const { logMessages } = useConsoleSpy();
+
+beforeAll(beforeAllCalls);
+afterAll(afterAllCalls);
+
+beforeEach(async () => {
+	await mkdir(tmpPath, { recursive: true });
+	vitest.stubEnv('HOME', tmpPath);
+	vitest.stubEnv('PATH', '');
+});
+
+afterEach(() => {
+	process.exitCode = undefined;
+	vitest.unstubAllEnvs();
+});
+
+const FIXED_TS = '2026-01-01T00:00:00.000Z';
+
+async function seedState(clients: string[]): Promise<void> {
+	const state: AgentState = {
+		installedAt: FIXED_TS,
+		clients: clients.map((c) => ({
+			client: c,
+			tier: 'mcp',
+			installedAt: FIXED_TS,
+		})),
+	};
+	await writeAgentState(state);
+}
+
+// ── No state ──────────────────────────────────────────────────────────────────
+
+describe('apify agent status', () => {
+	describe('no state', () => {
+		it('prints a "no agents configured" message when state file is absent', async () => {
+			await testRunCommand(AgentStatusCommand, {});
+
+			expect(process.exitCode).toBeUndefined();
+			expect(logMessages.error.join('\n')).toMatch(/No agents configured/);
+		});
+
+		it('exits 0 when no state file', async () => {
+			await testRunCommand(AgentStatusCommand, {});
+			expect(process.exitCode).toBeUndefined();
+		});
+
+		it('--json outputs { clients: [] } when no state file', async () => {
+			await testRunCommand(AgentStatusCommand, { flags_json: true });
+
+			const raw = logMessages.log.find((m) => m.startsWith('{'));
+			expect(raw).toBeDefined();
+			expect(JSON.parse(raw!)).toEqual({ clients: [] });
+		});
+
+		it('mentions `apify agent setup` in the no-agents message', async () => {
+			await testRunCommand(AgentStatusCommand, {});
+			expect(logMessages.error.join('\n')).toMatch(/apify agent setup/);
+		});
+	});
+
+	// ── Empty state ─────────────────────────────────────────────────────────────
+
+	describe('empty state (state file exists but clients array is empty)', () => {
+		it('prints "no agents configured" when state exists but has no clients', async () => {
+			await seedState([]);
+			await testRunCommand(AgentStatusCommand, {});
+
+			expect(process.exitCode).toBeUndefined();
+			expect(logMessages.error.join('\n')).toMatch(/No agents configured/);
+		});
+
+		it('--json outputs { clients: [] } when state has no clients', async () => {
+			await seedState([]);
+			await testRunCommand(AgentStatusCommand, { flags_json: true });
+
+			const raw = logMessages.log.find((m) => m.startsWith('{'));
+			expect(JSON.parse(raw!)).toEqual({ clients: [] });
+		});
+	});
+
+	// ── With state ──────────────────────────────────────────────────────────────
+
+	describe('with state', () => {
+		it('shows all configured clients when state exists', async () => {
+			await seedState(['cursor', 'kiro']);
+			await testRunCommand(AgentStatusCommand, {});
+
+			const out = logMessages.error.join('\n');
+			expect(out).toMatch(/cursor/);
+			expect(out).toMatch(/kiro/);
+		});
+
+		it('shows the tier for each client', async () => {
+			await seedState(['cursor']);
+			await testRunCommand(AgentStatusCommand, {});
+			expect(logMessages.error.join('\n')).toMatch(/mcp tier/);
+		});
+
+		it('exits 0 with configured clients', async () => {
+			await seedState(['cursor']);
+			await testRunCommand(AgentStatusCommand, {});
+			expect(process.exitCode).toBeUndefined();
+		});
+
+		it('human-readable output includes the install date', async () => {
+			await seedState(['cursor']);
+			await testRunCommand(AgentStatusCommand, {});
+
+			// FIXED_TS = '2026-01-01T00:00:00.000Z' → toLocaleDateString() is locale-dependent
+			// but must contain at least the year 2026.
+			expect(logMessages.error.join('\n')).toMatch(/2026/);
+		});
+
+		it('--json outputs clients array with correct shape', async () => {
+			await seedState(['cursor']);
+			await testRunCommand(AgentStatusCommand, { flags_json: true });
+
+			const raw = logMessages.log.find((m) => m.startsWith('{'));
+			const json = JSON.parse(raw!) as {
+				clients: {
+					client: string;
+					tier: string;
+					installedAt: string;
+				}[];
+			};
+			expect(json.clients).toHaveLength(1);
+			expect(json.clients[0]).toMatchObject({
+				client: 'cursor',
+				tier: 'mcp',
+				installedAt: FIXED_TS,
+			});
+		});
+
+		it('--json output contains all configured clients', async () => {
+			await seedState(['cursor', 'claude-code', 'kiro']);
+			await testRunCommand(AgentStatusCommand, { flags_json: true });
+
+			const raw = logMessages.log.find((m) => m.startsWith('{'));
+			const json = JSON.parse(raw!) as { clients: { client: string }[] };
+			expect(json.clients.map((c) => c.client)).toEqual(expect.arrayContaining(['cursor', 'claude-code', 'kiro']));
+		});
+	});
+
+	// ── --client flag ─────────────────────────────────────────────────────────
+
+	describe('--client flag', () => {
+		it('rejects unknown client with InvalidInput exit code', async () => {
+			await testRunCommand(AgentStatusCommand, {
+				flags_client: 'notaclient',
+			});
+			expect(process.exitCode).toBe(CommandExitCodes.InvalidInput);
+		});
+
+		it('shows status for only the targeted client', async () => {
+			await seedState(['cursor', 'kiro']);
+			await testRunCommand(AgentStatusCommand, {
+				flags_client: 'cursor',
+			});
+
+			const out = logMessages.error.join('\n');
+			expect(out).toMatch(/cursor/);
+			expect(out).not.toMatch(/kiro/);
+		});
+
+		it('reports not-configured when --client targets an absent client', async () => {
+			await seedState(['kiro']);
+			await testRunCommand(AgentStatusCommand, {
+				flags_client: 'cursor',
+			});
+
+			expect(process.exitCode).toBeUndefined();
+			expect(logMessages.error.join('\n')).toMatch(/not configured/i);
+		});
+
+		it('--client with --json returns { clients: [] } when client is not configured', async () => {
+			await seedState(['kiro']);
+			await testRunCommand(AgentStatusCommand, {
+				flags_client: 'cursor',
+				flags_json: true,
+			});
+
+			const raw = logMessages.log.find((m) => m.startsWith('{'));
+			expect(JSON.parse(raw!)).toEqual({ clients: [] });
+		});
+
+		it('--client with --json returns the matching entry when configured', async () => {
+			await seedState(['cursor']);
+			await testRunCommand(AgentStatusCommand, {
+				flags_client: 'cursor',
+				flags_json: true,
+			});
+
+			const raw = logMessages.log.find((m) => m.startsWith('{'));
+			const json = JSON.parse(raw!) as { clients: { client: string }[] };
+			expect(json.clients).toHaveLength(1);
+			expect(json.clients[0].client).toBe('cursor');
+		});
+	});
+
+	// ── Security ────────────────────────────────────────────────────────────────
+
+	describe('security', () => {
+		it('stdout does not contain any bearer token patterns', async () => {
+			await writeFile(
+				`${tmpPath}/.cursor/mcp.json`,
+				JSON.stringify({
+					mcpServers: {
+						apify: {
+							url: 'https://mcp.apify.com',
+							headers: {
+								Authorization: 'Bearer apify_api_SECRET',
+							},
+						},
+					},
+				}),
+			).catch(() => undefined);
+			await seedState(['cursor']);
+			await testRunCommand(AgentStatusCommand, { flags_json: true });
+
+			const allOutput = [...logMessages.log, ...logMessages.error].join('\n');
+			expect(allOutput).not.toMatch(/apify_api_/i);
+			expect(allOutput).not.toMatch(/Bearer /i);
+		});
+	});
+});
diff --git a/test/local/commands/agent/uninstall.test.ts b/test/local/commands/agent/uninstall.test.ts
new file mode 100644
index 000000000..34ed44851
--- /dev/null
+++ b/test/local/commands/agent/uninstall.test.ts
@@ -0,0 +1,532 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import process from 'node:process';
+
+vitest.mock('ci-info', async (importOriginal) => {
+	const original = await importOriginal<typeof import('ci-info')>();
+	return { ...original, isCI: true };
+});
+
+import { AgentUninstallCommand } from '../../../../src/commands/agent/uninstall.js';
+import {
+	isClientConfigured,
+	readAgentState,
+	writeAgentState,
+	type AgentState,
+} from '../../../../src/lib/agent/state.js';
+import { testRunCommand } from '../../../../src/lib/command-framework/apify-command.js';
+import { CommandExitCodes } from '../../../../src/lib/consts.js';
+import { useAuthSetup } from '../../../__setup__/hooks/useAuthSetup.js';
+import { useConsoleSpy } from '../../../__setup__/hooks/useConsoleSpy.js';
+import { useTempPath } from '../../../__setup__/hooks/useTempPath.js';
+
+const { tmpPath, joinPath, beforeAllCalls, afterAllCalls } = useTempPath('agent-uninstall');
+
+useAuthSetup();
+const { logMessages } = useConsoleSpy();
+
+beforeAll(beforeAllCalls);
+afterAll(afterAllCalls);
+
+beforeEach(async () => {
+	await rm(tmpPath, { recursive: true, force: true });
+	await mkdir(tmpPath, { recursive: true });
+	vitest.stubEnv('HOME', tmpPath);
+	vitest.stubEnv('PATH', '');
+});
+
+afterEach(() => {
+	process.exitCode = undefined;
+	vitest.unstubAllEnvs();
+});
+
+const FIXED_TS = '2026-01-01T00:00:00.000Z';
+
+async function seedState(clients: string[]): Promise<AgentState> {
+	const state: AgentState = {
+		installedAt: FIXED_TS,
+		clients: clients.map((c) => ({
+			client: c,
+			tier: 'mcp',
+			installedAt: FIXED_TS,
+		})),
+	};
+	await writeAgentState(state);
+	return state;
+}
+
+async function writeCursorConfig(content: Record<string, unknown> = {}): Promise<void> {
+	await mkdir(joinPath('.cursor'), { recursive: true });
+	await writeFile(joinPath('.cursor', 'mcp.json'), JSON.stringify(content), 'utf-8');
+}
+
+async function readCursorConfig(): Promise<Record<string, unknown>> {
+	return JSON.parse(await readFile(joinPath('.cursor', 'mcp.json'), 'utf-8')) as Record<string, unknown>;
+}
+
+function parsedJsonOutput(): Record<string, unknown> {
+	const raw = logMessages.log.find((m) => m.startsWith('{'));
+	if (!raw) throw new Error('No JSON output found in stdout');
+	return JSON.parse(raw) as Record<string, unknown>;
+}
+
+// ── Nothing to do ────────────────────────────────────────────────────────────
+
+describe('apify agent uninstall', () => {
+	describe('nothing to do', () => {
+		it('exits 0 with a message when no state file exists', async () => {
+			await testRunCommand(AgentUninstallCommand, { flags_yes: true });
+
+			expect(process.exitCode).toBeUndefined();
+			expect(logMessages.error.join('\n')).toMatch(/No agents configured/);
+		});
+
+		it('--json outputs { clients: [] } when nothing is configured', async () => {
+			await testRunCommand(AgentUninstallCommand, {
+				flags_yes: true,
+				flags_json: true,
+			});
+
+			expect(parsedJsonOutput()).toEqual({ clients: [] });
+		});
+
+		it('--client on unconfigured client reports not_configured, exits 0', async () => {
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			expect(process.exitCode).toBeUndefined();
+			expect(logMessages.error.join('\n')).toMatch(/not configured/i);
+		});
+
+		it('--client not_configured with --json includes outcome field', async () => {
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+				flags_json: true,
+			});
+
+			const json = parsedJsonOutput();
+			const clients = json.clients as {
+				client: string;
+				outcome: string;
+			}[];
+			expect(clients[0]).toMatchObject({
+				client: 'cursor',
+				outcome: 'not_configured',
+			});
+		});
+	});
+
+	// ── --client flag validation ──────────────────────────────────────────────
+
+	describe('--client flag validation', () => {
+		it('rejects unknown client with InvalidInput exit code', async () => {
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'notaclient',
+				flags_yes: true,
+			});
+			expect(process.exitCode).toBe(CommandExitCodes.InvalidInput);
+		});
+
+		it('error message names the invalid client', async () => {
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'notaclient',
+				flags_yes: true,
+			});
+			expect(logMessages.error.join('\n')).toMatch(/Unknown client 'notaclient'/);
+		});
+	});
+
+	// ── Confirmation prompt ───────────────────────────────────────────────────
+
+	describe('confirmation prompt', () => {
+		it('isCI=true without --yes logs "Re-run with --yes" and sets exit code', async () => {
+			await seedState(['cursor']);
+
+			// _run catches the stdinCheckWrapper throw, logs it, and sets exitCode.
+			// testRunCommand resolves (does not reject) — assert on observable side effects.
+			await testRunCommand(AgentUninstallCommand, {});
+
+			expect(process.exitCode).toBeDefined();
+			expect(logMessages.error.join('\n')).toMatch(/Re-run with --yes/);
+		});
+
+		it('--yes skips the prompt and proceeds', async () => {
+			await seedState(['cursor']);
+			await writeCursorConfig({
+				mcpServers: { apify: { url: 'https://mcp.apify.com' } },
+			});
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			expect(process.exitCode).toBeUndefined();
+		});
+
+		it('without --yes the state file is left unchanged', async () => {
+			await seedState(['cursor']);
+
+			await testRunCommand(AgentUninstallCommand, {});
+
+			// Whether the prompt threw (non-interactive) or returned false (declined),
+			// the state update block is never reached — cursor must still be present.
+			const state = await readAgentState();
+			expect(isClientConfigured(state!, 'cursor')).toBe(true);
+		});
+	});
+
+	// ── Happy path — file-based client (cursor) ───────────────────────────────
+
+	describe('happy path — file-based client (cursor)', () => {
+		it('removes the apify key from cursor mcp.json', async () => {
+			await seedState(['cursor']);
+			await writeCursorConfig({
+				mcpServers: {
+					apify: {
+						url: 'https://mcp.apify.com',
+						headers: { Authorization: 'Bearer tok' },
+					},
+					'other-server': { url: 'https://other.example.com' },
+				},
+			});
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			expect(process.exitCode).toBeUndefined();
+			const config = await readCursorConfig();
+			const servers = config.mcpServers as Record<string, unknown>;
+			expect(servers).not.toHaveProperty('apify');
+			expect(servers).toHaveProperty('other-server');
+		});
+
+		it('preserves other servers in the config file after removal', async () => {
+			await seedState(['cursor']);
+			await writeCursorConfig({
+				mcpServers: {
+					apify: { url: 'https://mcp.apify.com' },
+					'keep-me': { url: 'https://keep.example.com' },
+				},
+			});
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const config = await readCursorConfig();
+			const servers = config.mcpServers as Record<string, unknown>;
+			expect(servers).toHaveProperty('keep-me');
+		});
+
+		it('removes cursor from the state file after uninstall', async () => {
+			await seedState(['cursor', 'kiro']);
+			await writeCursorConfig({
+				mcpServers: { apify: { url: 'https://mcp.apify.com' } },
+			});
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const state = await readAgentState();
+			expect(isClientConfigured(state!, 'cursor')).toBe(false);
+			expect(isClientConfigured(state!, 'kiro')).toBe(true);
+		});
+
+		it('state file still exists after uninstalling one of many clients', async () => {
+			await seedState(['cursor', 'kiro']);
+			await writeCursorConfig({
+				mcpServers: { apify: { url: 'https://mcp.apify.com' } },
+			});
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const state = await readAgentState();
+			expect(state).not.toBeNull();
+		});
+
+		it('state file has zero clients after uninstalling the only configured client', async () => {
+			await seedState(['cursor']);
+			await writeCursorConfig({
+				mcpServers: { apify: { url: 'https://mcp.apify.com' } },
+			});
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const state = await readAgentState();
+			expect(state!.clients).toHaveLength(0);
+		});
+
+		it('gracefully handles cursor config file already missing the apify entry', async () => {
+			await seedState(['cursor']);
+			await writeCursorConfig({
+				mcpServers: {
+					'other-server': { url: 'https://other.example.com' },
+				},
+			});
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			// Should still exit 0 — nothing to remove is not a failure
+			expect(process.exitCode).toBeUndefined();
+		});
+
+		it('gracefully handles cursor config file entirely absent', async () => {
+			await seedState(['cursor']);
+			// No writeCursorConfig call — the file does not exist at all
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			expect(process.exitCode).toBeUndefined();
+		});
+
+		it('removes cursor from state even when config file was absent', async () => {
+			await seedState(['cursor', 'kiro']);
+			// No cursor config file — removeServerEntry returns false
+			await mkdir(joinPath('.kiro', 'settings'), { recursive: true });
+			await writeFile(
+				joinPath('.kiro', 'settings', 'mcp.json'),
+				JSON.stringify({
+					mcpServers: { apify: { url: 'https://mcp.apify.com' } },
+				}),
+				'utf-8',
+			);
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const state = await readAgentState();
+			expect(isClientConfigured(state!, 'cursor')).toBe(false);
+		});
+	});
+
+	// ── Uninstall all ─────────────────────────────────────────────────────────
+
+	describe('uninstall all (no --client)', () => {
+		it('uninstalls all configured file-based clients', async () => {
+			await seedState(['cursor', 'kiro']);
+
+			await mkdir(joinPath('.cursor'), { recursive: true });
+			await writeFile(
+				joinPath('.cursor', 'mcp.json'),
+				JSON.stringify({
+					mcpServers: { apify: { url: 'https://mcp.apify.com' } },
+				}),
+				'utf-8',
+			);
+			await mkdir(joinPath('.kiro', 'settings'), { recursive: true });
+			await writeFile(
+				joinPath('.kiro', 'settings', 'mcp.json'),
+				JSON.stringify({
+					mcpServers: { apify: { url: 'https://mcp.apify.com' } },
+				}),
+				'utf-8',
+			);
+
+			await testRunCommand(AgentUninstallCommand, { flags_yes: true });
+
+			const state = await readAgentState();
+			expect(state!.clients).toHaveLength(0);
+		});
+
+		it('--json output lists all uninstalled clients', async () => {
+			await seedState(['cursor', 'kiro']);
+			await mkdir(joinPath('.cursor'), { recursive: true });
+			await writeFile(joinPath('.cursor', 'mcp.json'), JSON.stringify({ mcpServers: { apify: {} } }), 'utf-8');
+			await mkdir(joinPath('.kiro', 'settings'), { recursive: true });
+			await writeFile(
+				joinPath('.kiro', 'settings', 'mcp.json'),
+				JSON.stringify({ mcpServers: { apify: {} } }),
+				'utf-8',
+			);
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_yes: true,
+				flags_json: true,
+			});
+
+			const json = parsedJsonOutput();
+			const clients = json.clients as {
+				client: string;
+				outcome: string;
+			}[];
+			expect(clients.map((c) => c.client)).toEqual(expect.arrayContaining(['cursor', 'kiro']));
+			for (const c of clients) expect(c.outcome).toBe('uninstalled');
+		});
+	});
+
+	// ── --json output shape ───────────────────────────────────────────────────
+
+	describe('--json output shape', () => {
+		it('outcome is "uninstalled" for a successfully removed client', async () => {
+			await seedState(['cursor']);
+			await writeCursorConfig({
+				mcpServers: { apify: { url: 'https://mcp.apify.com' } },
+			});
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+				flags_json: true,
+			});
+
+			const clients = parsedJsonOutput().clients as {
+				client: string;
+				outcome: string;
+			}[];
+			expect(clients.find((c) => c.client === 'cursor')?.outcome).toBe('uninstalled');
+		});
+
+		it('"reason" field is NOT present in JSON output', async () => {
+			await seedState(['cursor']);
+			await writeCursorConfig({
+				mcpServers: { apify: { url: 'https://mcp.apify.com' } },
+			});
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+				flags_json: true,
+			});
+
+			const clients = parsedJsonOutput().clients as Record<string, unknown>[];
+			for (const entry of clients) expect(entry).not.toHaveProperty('reason');
+		});
+	});
+
+	// ── CLI-based client failure ──────────────────────────────────────────────
+
+	describe('CLI-based client failure (binary not found)', () => {
+		it('claude-code: binary not on PATH → outcome=failed, RunFailed exit code', async () => {
+			await seedState(['claude-code']);
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'claude-code',
+				flags_yes: true,
+			});
+
+			expect(process.exitCode).toBe(CommandExitCodes.RunFailed);
+		});
+
+		it('failed client is NOT removed from the state file', async () => {
+			await seedState(['claude-code']);
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'claude-code',
+				flags_yes: true,
+			});
+
+			const state = await readAgentState();
+			expect(isClientConfigured(state!, 'claude-code')).toBe(true);
+		});
+
+		it('partial failure: cursor succeeds, claude-code fails → RunFailed + cursor removed, claude-code kept', async () => {
+			await seedState(['cursor', 'claude-code']);
+			await writeCursorConfig({
+				mcpServers: { apify: { url: 'https://mcp.apify.com' } },
+			});
+
+			await testRunCommand(AgentUninstallCommand, { flags_yes: true });
+
+			// Overall result is failure because claude-code failed
+			expect(process.exitCode).toBe(CommandExitCodes.RunFailed);
+
+			// cursor succeeded → removed from state
+			const state = await readAgentState();
+			expect(isClientConfigured(state!, 'cursor')).toBe(false);
+
+			// claude-code failed → kept in state
+			expect(isClientConfigured(state!, 'claude-code')).toBe(true);
+		});
+
+		it('partial failure --json: cursor outcome=uninstalled, claude-code outcome=failed', async () => {
+			await seedState(['cursor', 'claude-code']);
+			await writeCursorConfig({
+				mcpServers: { apify: { url: 'https://mcp.apify.com' } },
+			});
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_yes: true,
+				flags_json: true,
+			});
+
+			const json = parsedJsonOutput();
+			const clients = json.clients as {
+				client: string;
+				outcome: string;
+			}[];
+			const cursorEntry = clients.find((c) => c.client === 'cursor');
+			const claudeEntry = clients.find((c) => c.client === 'claude-code');
+			expect(cursorEntry?.outcome).toBe('uninstalled');
+			expect(claudeEntry?.outcome).toBe('failed');
+		});
+	});
+
+	// ── Security ─────────────────────────────────────────────────────────────
+
+	describe('security', () => {
+		it('no bearer token appears in any output after uninstall', async () => {
+			await seedState(['cursor']);
+			await writeCursorConfig({
+				mcpServers: {
+					apify: {
+						url: 'https://mcp.apify.com',
+						headers: { Authorization: 'Bearer apify_api_SECRET' },
+					},
+				},
+			});
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			const allOutput = [...logMessages.log, ...logMessages.error].join('\n');
+			expect(allOutput).not.toMatch(/apify_api_/i);
+		});
+
+		it('cursor config file does not contain the token after uninstall', async () => {
+			await seedState(['cursor']);
+			await writeCursorConfig({
+				mcpServers: {
+					apify: {
+						url: 'https://mcp.apify.com',
+						headers: { Authorization: 'Bearer apify_api_SECRET' },
+					},
+					'other-server': { url: 'https://other.example.com' },
+				},
+			});
+
+			await testRunCommand(AgentUninstallCommand, {
+				flags_client: 'cursor',
+				flags_yes: true,
+			});
+
+			expect(existsSync(joinPath('.cursor', 'mcp.json'))).toBe(true);
+			const raw = await readFile(joinPath('.cursor', 'mcp.json'), 'utf-8');
+			expect(raw).not.toMatch(/apify_api_SECRET/);
+		});
+	});
+});