refactor(cli): rename --agent flags to --runtime across all commands

Rename CLI flags from agent terminology to runtime:
- --agent <name> → --runtime <name> (with -a → -r short alias)
- --agent-runtime-id → --runtime-id
- --agent-arn → --runtime-arn
- --agents → --runtimes (gateway primitive)

Update resolveAgent() to accept { runtime?: string }.
Update all action handlers, option types, error messages, and tests.

Keep --agent-id and --agent-alias-id unchanged (Bedrock Agent IDs).
Keep 'agentcore add agent' / 'agentcore remove agent' commands unchanged.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jesseturner21

src/cli/commands/add/types.ts

@@ -57,6 +57,7 @@ export interface AddGatewayOptions {
   customClaims?: string;
   clientId?: string;
   clientSecret?: string;
+  runtimes?: string;
   semanticSearch?: boolean;
   exceptionLevel?: string;
   policyEngine?: string;

src/cli/commands/dev/__tests__/dev.test.ts

@@ -8,7 +8,7 @@ describe('dev command', () => {
 
       expect(result.exitCode).toBe(0);
       expect(result.stdout.includes('--port'), 'Should show --port option').toBeTruthy();
-      expect(result.stdout.includes('--agent'), 'Should show --agent option').toBeTruthy();
+      expect(result.stdout.includes('--runtime'), 'Should show --runtime option').toBeTruthy();
       expect(result.stdout.includes('--invoke'), 'Should show --invoke option').toBeTruthy();
       expect(result.stdout.includes('--stream'), 'Should show --stream option').toBeTruthy();
       expect(result.stdout.includes('--logs'), 'Should show --logs option').toBeTruthy();

src/cli/commands/dev/command.tsx

@@ -138,8 +138,8 @@ export const registerDev = (program: Command) => {
     .alias('d')
     .description(COMMAND_DESCRIPTIONS.dev)
     .option('-p, --port <port>', 'Port for development server', '8080')
-    .option('-a, --agent <name>', 'Agent to run or invoke (required if multiple agents)')
-    .option('-i, --invoke <prompt>', 'Invoke running dev server (use --agent if multiple) [non-interactive]')
+    .option('-r, --runtime <name>', 'Runtime to run or invoke (required if multiple runtimes)')
+    .option('-i, --invoke <prompt>', 'Invoke running dev server (use --runtime if multiple) [non-interactive]')
     .option('-s, --stream', 'Stream response when using --invoke [non-interactive]')
     .option('-l, --logs', 'Run dev server with logs to stdout [non-interactive]')
     .option('--tool <name>', 'MCP tool name (used with --invoke call-tool) [non-interactive]')
@@ -167,12 +167,12 @@ export const registerDev = (program: Command) => {
           // Determine which agent/port to invoke
           let invokePort = port;
           let targetAgent = invokeProject?.runtimes[0];
-          if (opts.agent && invokeProject) {
-            invokePort = getAgentPort(invokeProject, opts.agent, port);
-            targetAgent = invokeProject.runtimes.find(a => a.name === opts.agent);
-          } else if (invokeProject && invokeProject.runtimes.length > 1 && !opts.agent) {
+          if (opts.runtime && invokeProject) {
+            invokePort = getAgentPort(invokeProject, opts.runtime, port);
+            targetAgent = invokeProject.runtimes.find(a => a.name === opts.runtime);
+          } else if (invokeProject && invokeProject.runtimes.length > 1 && !opts.runtime) {
             const names = invokeProject.runtimes.map(a => a.name).join(', ');
-            console.error(`Error: Multiple agents found. Use --agent to specify which one.`);
+            console.error(`Error: Multiple runtimes found. Use --runtime to specify which one.`);
             console.error(`Available: ${names}`);
             process.exit(1);
           }
@@ -210,7 +210,7 @@ export const registerDev = (program: Command) => {
         }
 
         // Warn about VPC mode limitations in local dev
-        const targetDevAgent = opts.agent ? project.runtimes.find(a => a.name === opts.agent) : project.runtimes[0];
+        const targetDevAgent = opts.runtime ? project.runtimes.find(a => a.name === opts.runtime) : project.runtimes[0];
         if (targetDevAgent?.networkMode === 'VPC') {
           console.log(
             '\x1b[33mWarning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.\x1b[0m\n'
@@ -228,14 +228,14 @@ export const registerDev = (program: Command) => {
         // If --logs provided, run non-interactive mode
         if (opts.logs) {
           // Require --agent if multiple agents
-          if (project.runtimes.length > 1 && !opts.agent) {
+          if (project.runtimes.length > 1 && !opts.runtime) {
             const names = project.runtimes.map(a => a.name).join(', ');
-            console.error(`Error: Multiple agents found. Use --agent to specify which one.`);
+            console.error(`Error: Multiple runtimes found. Use --runtime to specify which one.`);
             console.error(`Available: ${names}`);
             process.exit(1);
           }
 
-          const agentName = opts.agent ?? project.runtimes[0]?.name;
+          const agentName = opts.runtime ?? project.runtimes[0]?.name;
           const configRoot = findConfigRoot(workingDir);
           const envVars = configRoot ? await readEnvFile(configRoot) : {};
           const gatewayEnvVars = await getGatewayEnvVars();
@@ -325,7 +325,7 @@ export const registerDev = (program: Command) => {
               }}
               workingDir={workingDir}
               port={port}
-              agentName={opts.agent}
+              agentName={opts.runtime}
               headers={headers}
             />
           </LayoutProvider>

src/cli/commands/eval/command.tsx

@@ -13,15 +13,15 @@ export const registerEval = (program: Command) => {
   evalCmd
     .command('history')
     .description('Show past on-demand eval run results saved locally')
-    .option('-a, --agent <name>', 'Filter results by agent name')
+    .option('-r, --runtime <name>', 'Filter results by runtime name')
     .option('-n, --limit <count>', 'Max number of runs to display')
     .option('--json', 'Output as JSON')
-    .action((cliOptions: { agent?: string; limit?: string; json?: boolean }) => {
+    .action((cliOptions: { runtime?: string; limit?: string; json?: boolean }) => {
       requireProject();
 
       try {
         const result = handleListEvalRuns({
-          agent: cliOptions.agent,
+          agent: cliOptions.runtime,
           limit: cliOptions.limit ? parseInt(cliOptions.limit, 10) : undefined,
           json: cliOptions.json,
         });

src/cli/commands/help/command.tsx

@@ -34,7 +34,7 @@ FLAGS THAT TRIGGER CLI MODE
     --name, --json, --yes, --force, --target, --stream, etc.
   
   Some flags work in both modes:
-    --session-id (invoke), --port (dev), --agent (dev)
+    --session-id (invoke), --port (dev), --runtime (dev)
 `;
 
 export const registerHelp = (program: Command) => {

src/cli/commands/invoke/__tests__/invoke.test.ts

@@ -61,7 +61,7 @@ describe('invoke command', () => {
 
   describe('agent validation', () => {
     it('rejects non-existent agent', async () => {
-      const result = await runCLI(['invoke', 'hello', '--agent', 'nonexistent', '--json'], projectDir);
+      const result = await runCLI(['invoke', 'hello', '--runtime', 'nonexistent', '--json'], projectDir);
       expect(result.exitCode).toBe(1);
       const json = JSON.parse(result.stdout);
       expect(json.success).toBe(false);
@@ -82,7 +82,7 @@ describe('invoke command', () => {
     });
 
     it('--stream with invalid agent returns error', async () => {
-      const result = await runCLI(['invoke', 'hello', '--stream', '--agent', 'nonexistent', '--json'], projectDir);
+      const result = await runCLI(['invoke', 'hello', '--stream', '--runtime', 'nonexistent', '--json'], projectDir);
       expect(result.exitCode).toBe(1);
       const json = JSON.parse(result.stdout);
       expect(json.success).toBe(false);

src/cli/commands/invoke/action.ts

@@ -63,7 +63,7 @@ export async function handleInvoke(context: InvokeContext, options: InvokeOption
   const agentNames = project.runtimes.map(a => a.name);
 
   if (!options.agentName && project.runtimes.length > 1) {
-    return { success: false, error: `Multiple agents found. Use --agent to specify one: ${agentNames.join(', ')}` };
+    return { success: false, error: `Multiple runtimes found. Use --runtime to specify one: ${agentNames.join(', ')}` };
   }
 
   const agentSpec = options.agentName ? project.runtimes.find(a => a.name === options.agentName) : project.runtimes[0];

src/cli/commands/invoke/command.tsx

@@ -96,7 +96,7 @@ export const registerInvoke = (program: Command) => {
     .description(COMMAND_DESCRIPTIONS.invoke)
     .argument('[prompt]', 'Prompt to send to the agent [non-interactive]')
     .option('--prompt <text>', 'Prompt to send to the agent [non-interactive]')
-    .option('--agent <name>', 'Select specific agent [non-interactive]')
+    .option('--runtime <name>', 'Select specific runtime [non-interactive]')
     .option('--target <name>', 'Select deployment target [non-interactive]')
     .option('--session-id <id>', 'Use specific session ID for conversation continuity')
     .option('--user-id <id>', 'User ID for runtime invocation (default: "default-user")')
@@ -116,7 +116,7 @@ export const registerInvoke = (program: Command) => {
         positionalPrompt: string | undefined,
         cliOptions: {
           prompt?: string;
-          agent?: string;
+          runtime?: string;
           target?: string;
           sessionId?: string;
           userId?: string;
@@ -145,13 +145,13 @@ export const registerInvoke = (program: Command) => {
             cliOptions.json ||
             cliOptions.target ||
             cliOptions.stream ||
-            cliOptions.agent ||
+            cliOptions.runtime ||
             cliOptions.tool ||
             cliOptions.bearerToken
           ) {
             await handleInvokeCLI({
               prompt,
-              agentName: cliOptions.agent,
+              agentName: cliOptions.runtime,
               targetName: cliOptions.target ?? 'default',
               sessionId: cliOptions.sessionId,
               userId: cliOptions.userId,

src/cli/commands/logs/__tests__/action.test.ts

@@ -126,7 +126,7 @@ describe('resolveAgentContext', () => {
     const result = resolveAgentContext(context, {});
     expect(result.success).toBe(false);
     if (!result.success) {
-      expect(result.error).toContain('Multiple agents found');
+      expect(result.error).toContain('Multiple runtimes found');
       expect(result.error).toContain('AgentA');
       expect(result.error).toContain('AgentB');
     }
@@ -184,7 +184,7 @@ describe('resolveAgentContext', () => {
         },
       },
     });
-    const result = resolveAgentContext(context, { agent: 'AgentB' });
+    const result = resolveAgentContext(context, { runtime: 'AgentB' });
     expect(result.success).toBe(true);
     if (result.success) {
       expect(result.agentContext.agentName).toBe('AgentB');
@@ -193,10 +193,10 @@ describe('resolveAgentContext', () => {
   });
 
   it('errors for unknown agent name', () => {
-    const result = resolveAgentContext(makeContext(), { agent: 'UnknownAgent' });
+    const result = resolveAgentContext(makeContext(), { runtime: 'UnknownAgent' });
     expect(result.success).toBe(false);
     if (!result.success) {
-      expect(result.error).toContain("Agent 'UnknownAgent' not found");
+      expect(result.error).toContain("Runtime 'UnknownAgent' not found");
     }
   });
 
@@ -218,7 +218,7 @@ describe('resolveAgentContext', () => {
     const result = resolveAgentContext(context, {});
     expect(result.success).toBe(false);
     if (!result.success) {
-      expect(result.error).toContain('No agents defined');
+      expect(result.error).toContain('No runtimes defined');
     }
   });
 

src/cli/commands/logs/command.tsx

@@ -10,7 +10,7 @@ import { Text, render } from 'ink';
 import React from 'react';
 
 export const registerLogs = (program: Command) => {
-  // enablePositionalOptions + passThroughOptions ensure options like --since and --agent
+  // enablePositionalOptions + passThroughOptions ensure options like --since and --runtime
   // are passed to the 'evals' subcommand rather than being consumed by the parent 'logs' command.
   program.enablePositionalOptions();
 
@@ -20,7 +20,7 @@ export const registerLogs = (program: Command) => {
     .enablePositionalOptions()
     .passThroughOptions()
     .description(COMMAND_DESCRIPTIONS.logs)
-    .option('--agent <name>', 'Select specific agent')
+    .option('--runtime <name>', 'Select specific runtime')
     .option('--since <time>', 'Start time — defaults to 1h ago in search mode (e.g. "1h", "30m", "2d", ISO 8601)')
     .option('--until <time>', 'End time — defaults to now in search mode (e.g. "now", ISO 8601)')
     .option('--level <level>', 'Filter by log level (error, warn, info, debug)')
@@ -46,7 +46,7 @@ export const registerLogs = (program: Command) => {
   logsCmd
     .command('evals')
     .description('Stream or search online eval logs')
-    .option('-a, --agent <name>', 'Select specific agent')
+    .option('-r, --runtime <name>', 'Select specific runtime')
     .option('--since <time>', 'Start time (e.g. "1h", "30m", "2d", ISO 8601)')
     .option('--until <time>', 'End time (e.g. "now", ISO 8601)')
     .option('-n, --limit <count>', 'Maximum number of log lines')