feat(agent): add Gemini CLI as an install target

src/commands/agent.test.ts

@@ -779,8 +779,8 @@ describe('runList', () => {
 
     const json = JSON.parse(capture.stdout.join('\n')) as ListResult[];
     expect(Array.isArray(json)).toBe(true);
-    // 8 targets × 2 default skills = 16 rows
-    expect(json).toHaveLength(16);
+    // 9 targets x 2 default skills = 18 rows
+    expect(json).toHaveLength(18);
     const targets = json.map(r => r.target);
     expect(targets).toContain('claude');
     expect(targets).toContain('cursor');

src/commands/agent.ts

@@ -1062,7 +1062,7 @@ function collect(v: string, prev: string[]): string[] {
 
 export function createAgentCommand(deps: AgentDeps = {}): Command {
   const agent = new Command('agent').description(
-    'Install TestSprite guidance into coding-agent config (Claude Code, Cursor, Cline, Antigravity, Kiro, Windsurf, Copilot, Codex)',
+    'Install TestSprite guidance into coding-agent config (Claude Code, Cursor, Cline, Antigravity, Kiro, Windsurf, Copilot, Gemini, Codex)',
   );
 
   agent
@@ -1072,7 +1072,7 @@ export function createAgentCommand(deps: AgentDeps = {}): Command {
     )
     .option(
       '--target <t>',
-      'Agent target(s): claude, cursor, cline, antigravity, kiro, windsurf, copilot, codex (comma-separated or repeated)',
+      'Agent target(s): claude, cursor, cline, antigravity, kiro, windsurf, copilot, gemini, codex (comma-separated or repeated)',
       collect,
       [],
     )
@@ -1086,7 +1086,7 @@ export function createAgentCommand(deps: AgentDeps = {}): Command {
     .option(
       '--force',
       'For own-file targets: overwrite existing file (a .bak backup is kept). ' +
-        'For codex (managed-section): replaces the section unconditionally; user content outside the section is never destroyed.',
+        'For managed-section targets (codex, gemini): replaces the section unconditionally; user content outside the section is never destroyed.',
     )
     .addHelpText('after', GLOBAL_OPTS_HINT)
     .action(

src/commands/auth.test.ts

@@ -1224,3 +1224,90 @@ describe('createAuthCommand surface', () => {
     expect(err.exitCode).toBe(3);
   });
 });
+
+// ---------------------------------------------------------------------------
+// runConfigure -- skipIfConfigured
+// ---------------------------------------------------------------------------
+
+describe('runConfigure -- skipIfConfigured', () => {
+  it('skips the prompt and returns early when credentials already exist', async () => {
+    const { capture, deps } = makeCapture();
+    // Write a saved key first.
+    writeProfile('default', { apiKey: 'sk-existing' }, { path: credentialsPath });
+    const prompt = { secret: vi.fn(async () => 'sk-new') };
+    const fetchImpl = vi.fn();
+
+    await runConfigure(
+      { profile: 'default', output: 'text', debug: false, fromEnv: false, skipIfConfigured: true },
+      {
+        ...deps,
+        credentialsPath,
+        prompt,
+        fetchImpl: fetchImpl as unknown as AuthDeps['fetchImpl'],
+      },
+    );
+
+    // Prompt must never have fired.
+    expect(prompt.secret).not.toHaveBeenCalled();
+    // No network call -- we never validated or wrote a key.
+    expect(fetchImpl).not.toHaveBeenCalled();
+    // The saved key must be untouched.
+    expect(readProfile('default', { path: credentialsPath })?.apiKey).toBe('sk-existing');
+    // Output indicates already_configured.
+    expect(capture.stdout.join('\n')).toContain('already configured');
+  });
+
+  it('emits already_configured status in JSON mode', async () => {
+    const { capture, deps } = makeCapture();
+    writeProfile('default', { apiKey: 'sk-saved' }, { path: credentialsPath });
+    const fetchImpl = vi.fn();
+
+    await runConfigure(
+      { profile: 'default', output: 'json', debug: false, fromEnv: false, skipIfConfigured: true },
+      { ...deps, credentialsPath, fetchImpl: fetchImpl as unknown as AuthDeps['fetchImpl'] },
+    );
+
+    expect(fetchImpl).not.toHaveBeenCalled();
+    const parsed = JSON.parse(capture.stdout.join(''));
+    expect(parsed).toMatchObject({ profile: 'default', status: 'already_configured' });
+  });
+
+  it('proceeds normally when no credentials exist and skipIfConfigured is true', async () => {
+    const { deps } = makeCapture();
+    // No pre-existing profile -- skip has no effect, should fall through to prompt.
+    const prompt = { secret: vi.fn(async () => 'sk-new') };
+
+    await runConfigure(
+      { profile: 'default', output: 'text', debug: false, fromEnv: false, skipIfConfigured: true },
+      { ...deps, credentialsPath, prompt, fetchImpl: meOkFetch },
+    );
+
+    expect(prompt.secret).toHaveBeenCalledTimes(1);
+    expect(readProfile('default', { path: credentialsPath })?.apiKey).toBe('sk-new');
+  });
+
+  it('ignores skipIfConfigured when --from-env is set', async () => {
+    const { deps } = makeCapture();
+    // Pre-existing key -- but fromEnv should override and write a new one.
+    writeProfile('default', { apiKey: 'sk-old' }, { path: credentialsPath });
+
+    await runConfigure(
+      {
+        profile: 'default',
+        output: 'text',
+        debug: false,
+        fromEnv: true,
+        skipIfConfigured: true,
+      },
+      {
+        ...deps,
+        env: { TESTSPRITE_API_KEY: 'sk-from-env' },
+        credentialsPath,
+        fetchImpl: meOkFetch,
+      },
+    );
+
+    // The env key must overwrite the saved key.
+    expect(readProfile('default', { path: credentialsPath })?.apiKey).toBe('sk-from-env');
+  });
+});

src/commands/auth.ts

@@ -65,6 +65,17 @@ type CommonOptions = FactoryCommonOptions;
 
 interface ConfigureOptions extends CommonOptions {
   fromEnv: boolean;
+  /**
+   * When true and the active profile already has a saved API key, skip the
+   * interactive key prompt and proceed directly to the skill-install step.
+   * A CI-safe flag: lets `setup` run idempotently without prompting on
+   * machines that already have credentials (e.g. re-running setup to
+   * refresh the agent skill without re-entering the key).
+   *
+   * Ignored when an explicit `--api-key` or `--from-env` key source is
+   * provided -- those paths always overwrite, regardless of existing state.
+   */
+  skipIfConfigured?: boolean;
 }
 
 const DEFAULT_API_URL = 'https://api.testsprite.com';
@@ -125,9 +136,23 @@ export async function runConfigure(opts: ConfigureOptions, deps: AuthDeps = {}):
     apiKey = env.TESTSPRITE_API_KEY?.trim();
     if (!apiKey) throw validationError('TESTSPRITE_API_KEY', FROM_ENV_MISSING_KEY);
   } else {
+    // --skip-if-configured: when a non-empty API key is already saved for
+    // this profile, skip the interactive prompt and return early. The
+    // key is NOT re-validated via GET /me on this path -- the caller
+    // (runInit) only reaches this when no explicit key source was given,
+    // and the subsequent whoami call in runInit will surface an expired
+    // key to the user anyway.
+    if (opts.skipIfConfigured && existingProfile?.apiKey) {
+      out.print({ profile: opts.profile, apiUrl, status: 'already_configured' }, data => {
+        const d = data as { profile: string; apiUrl: string };
+        return `Profile "${d.profile}" already configured. Endpoint: ${d.apiUrl}`;
+      });
+      return;
+    }
+
     const promptApi = deps.prompt ?? { secret: (q: string) => promptSecret(q) };
     prelude(`Configuring profile "${opts.profile}".\n`);
-    // Only the API key is prompted — the endpoint defaults to prod (see above).
+    // Only the API key is prompted -- the endpoint defaults to prod (see above).
     apiKey = (await promptApi.secret('TestSprite API key: ')).trim();
     if (!apiKey) throw new CLIError('No API key provided.', 5);
   }

src/commands/init.test.ts

@@ -9,6 +9,7 @@ import path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { ApiError, CLIError } from '../lib/errors.js';
 import { resetDryRunBannerForTesting } from '../lib/client-factory.js';
+import { readProfile, writeProfile } from '../lib/credentials.js';
 import type { MeResponse } from './auth.js';
 import type { AgentFs } from './agent.js';
 import type { InitDeps } from './init.js';
@@ -1006,3 +1007,99 @@ describe('runInit — telemetry attribution (X-CLI-Command)', () => {
     expect(initTagged).toHaveLength(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// runInit -- skipIfConfigured
+// ---------------------------------------------------------------------------
+
+describe('runInit -- skipIfConfigured', () => {
+  it('skips the API key prompt and reuses saved credentials when the profile exists', async () => {
+    const { captured, deps } = makeCapture();
+    const { fs: agentFs } = makeMemFs();
+    // Write a saved key before running setup.
+    writeProfile('default', { apiKey: 'sk-saved' }, { path: credentialsPath });
+    // Provide a mock fetch that accepts /me so runWhoami (identity banner) succeeds.
+    const fetchMock = makeOkFetch();
+    const prompt = { secret: vi.fn(async () => 'sk-should-never-be-asked') };
+
+    await runInit(makeBaseOpts({ skipIfConfigured: true, noAgent: true, output: 'json' }), {
+      ...deps,
+      credentialsPath,
+      fetchImpl: fetchMock,
+      fs: agentFs,
+      isTTY: false,
+      prompt,
+    });
+
+    // The prompt must never have fired.
+    expect(prompt.secret).not.toHaveBeenCalled();
+    // The saved key must be untouched.
+    expect(readProfile('default', { path: credentialsPath })?.apiKey).toBe('sk-saved');
+    // The summary must still be emitted.
+    const parsed = JSON.parse(captured.stdout.join('')) as { status: string };
+    expect(parsed.status).toBe('initialized');
+  });
+
+  it('proceeds to prompt when skipIfConfigured is true but no credentials exist', async () => {
+    const { captured, deps } = makeCapture();
+    const { fs: agentFs } = makeMemFs();
+    // No pre-existing credentials -- skip has no effect.
+    const fetchMock = makeOkFetch();
+    const prompt = { secret: vi.fn(async () => 'sk-fresh') };
+
+    await runInit(makeBaseOpts({ skipIfConfigured: true, noAgent: true, output: 'text' }), {
+      ...deps,
+      credentialsPath,
+      fetchImpl: fetchMock,
+      fs: agentFs,
+      isTTY: true,
+      prompt,
+    });
+
+    // With no saved key, the prompt should fire.
+    expect(prompt.secret).toHaveBeenCalledTimes(1);
+    expect(readProfile('default', { path: credentialsPath })?.apiKey).toBe('sk-fresh');
+    expect(captured.stdout.join('')).toContain('initialized');
+  });
+
+  it('allows non-interactive (isTTY=false) when skipIfConfigured is true and credentials exist', async () => {
+    const { deps } = makeCapture();
+    const { fs: agentFs } = makeMemFs();
+    writeProfile('default', { apiKey: 'sk-ci' }, { path: credentialsPath });
+    const fetchMock = makeOkFetch();
+
+    // Must not throw exit 5 for "non-interactive mode, no key source".
+    await expect(
+      runInit(makeBaseOpts({ skipIfConfigured: true, noAgent: true, output: 'json' }), {
+        ...deps,
+        credentialsPath,
+        fetchImpl: fetchMock,
+        fs: agentFs,
+        isTTY: false,
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(readProfile('default', { path: credentialsPath })?.apiKey).toBe('sk-ci');
+  });
+
+  it('--api-key takes precedence over skipIfConfigured and overwrites the saved key', async () => {
+    const { deps } = makeCapture();
+    const { fs: agentFs } = makeMemFs();
+    writeProfile('default', { apiKey: 'sk-old' }, { path: credentialsPath });
+    const fetchMock = makeOkFetch();
+
+    await runInit(
+      makeBaseOpts({ apiKey: 'sk-new', skipIfConfigured: true, noAgent: true, output: 'text' }),
+      {
+        ...deps,
+        credentialsPath,
+        fetchImpl: fetchMock,
+        fs: agentFs,
+        isTTY: false,
+      },
+    );
+
+    // Explicit --api-key must overwrite regardless of skipIfConfigured.
+    expect(readProfile('default', { path: credentialsPath })?.apiKey).toBe('sk-new');
+  });
+});

src/commands/init.ts

@@ -90,6 +90,12 @@ interface InitOptions extends CommonOptions {
   force: boolean;
   dir?: string;
   yes: boolean;
+  /**
+   * When true and the active profile already has a saved API key, skip the
+   * interactive key prompt. Forwarded verbatim to runConfigure. Has no
+   * effect when --api-key or --from-env is also given.
+   */
+  skipIfConfigured?: boolean;
   /** Set by the command action when both --agent and --no-agent appear in rawArgs. */
   rawArgConflict?: boolean;
 }
@@ -196,9 +202,16 @@ export async function runInit(opts: InitOptions, deps: InitDeps = {}): Promise<v
   // -------------------------------------------------------------------------
   const isTTY = deps.isTTY ?? Boolean(process.stdin.isTTY);
   const hasKeySource = Boolean(opts.apiKey) || opts.fromEnv;
+  // --skip-if-configured counts as a key source when a saved key already exists:
+  // runConfigure will short-circuit before prompting, so no TTY is needed.
+  const credentialsPath = deps.credentialsPath;
+  const savedKey = credentialsPath
+    ? readProfile(opts.profile, { path: credentialsPath })?.apiKey
+    : readProfile(opts.profile)?.apiKey;
+  const skipWillApply = Boolean(opts.skipIfConfigured) && Boolean(savedKey) && !hasKeySource;
   // Non-interactive guard: no TTY + no key source → exit 5. Skipped under
   // --dry-run, which is documented to work without credentials or network.
-  if (!isTTY && !hasKeySource && !opts.dryRun) {
+  if (!isTTY && !hasKeySource && !skipWillApply && !opts.dryRun) {
     throw new CLIError(
       'No API key available in non-interactive mode. ' +
         'Pass --api-key <key>, --from-env (reads TESTSPRITE_API_KEY), or run interactively.',
@@ -208,7 +221,7 @@ export async function runInit(opts: InitOptions, deps: InitDeps = {}): Promise<v
   // JSON-output guard: an interactive secret prompt writes to stdout and would
   // corrupt init's single-JSON-object output contract. In --output json mode
   // require a non-interactive key source. Skipped under --dry-run (never prompts).
-  if (opts.output === 'json' && !hasKeySource && !opts.dryRun) {
+  if (opts.output === 'json' && !hasKeySource && !skipWillApply && !opts.dryRun) {
     throw new CLIError(
       'Interactive API-key prompt is unavailable in --output json mode (it would corrupt JSON stdout). ' +
         'Pass --api-key <key> or --from-env.',
@@ -223,7 +236,13 @@ export async function runInit(opts: InitOptions, deps: InitDeps = {}): Promise<v
     stderrFn('[dry-run] no writes or network calls — preview only');
     stderrFn(
       `[dry-run] would configure profile="${opts.profile}" (key source: ${
-        opts.apiKey ? 'flag' : opts.fromEnv ? 'env' : 'prompt'
+        opts.apiKey
+          ? 'flag'
+          : opts.fromEnv
+            ? 'env'
+            : opts.skipIfConfigured
+              ? 'skip-if-configured'
+              : 'prompt'
       })`,
     );
 
@@ -265,7 +284,12 @@ export async function runInit(opts: InitOptions, deps: InitDeps = {}): Promise<v
   // force fromEnv=false so runConfigure uses the injected key (toAuthDeps wires it
   // as the prompt) instead of reading TESTSPRITE_API_KEY from the environment (codex).
   await runConfigure(
-    { ...opts, fromEnv: opts.apiKey ? false : opts.fromEnv },
+    {
+      ...opts,
+      fromEnv: opts.apiKey ? false : opts.fromEnv,
+      // --api-key always overwrites; skip only applies when no explicit key source was given.
+      skipIfConfigured: opts.apiKey ? false : opts.skipIfConfigured,
+    },
     // commandTag:'init' tags ONLY this configure-validate GET /me with
     // `X-CLI-Command: init` → counted as cli.initialized. The whoami banner call
     // below builds deps WITHOUT a tag, so init emits exactly one cli.initialized.
@@ -475,6 +499,7 @@ interface SetupCmdOpts {
   force?: boolean;
   dir?: string;
   yes?: boolean;
+  skipIfConfigured?: boolean;
 }
 
 /** Attach the onboarding flags shared by `setup` and the `init` alias. */
@@ -498,7 +523,11 @@ function addSetupOptions(
     .option('--no-agent', 'Skip the agent skill install (configure credentials only)')
     .option('--force', 'Overwrite an existing skill file (a .bak backup is kept)')
     .option('--dir <path>', 'Project root for the skill install (default: current directory)')
-    .option('-y, --yes', 'Non-interactive: accept all defaults, never prompt');
+    .option('-y, --yes', 'Non-interactive: accept all defaults, never prompt')
+    .option(
+      '--skip-if-configured',
+      'Skip the API key prompt when credentials already exist for this profile (CI-safe idempotent re-run)',
+    );
 }
 
 /** Build {@link InitOptions} from raw Commander opts + globals. */
@@ -539,6 +568,7 @@ function buildSetupOptions(
     force: Boolean(cmdOpts.force),
     dir: cmdOpts.dir,
     yes: Boolean(cmdOpts.yes),
+    skipIfConfigured: Boolean(cmdOpts.skipIfConfigured),
     rawArgConflict,
   };
 }