AgentCore CLI reference

This reference documents the public Amazon Bedrock AgentCore CLI releases.

Project Lifecycle

Auto-generated from @aws/agentcore v0.28.1 — do not edit by hand.

agentcore create

agentcore create [options]

Create a new AgentCore project

Parameters

--name <name> (optional)

Resource name [non-interactive]

--project-name <name> (optional)

Project name (start with letter, alphanumeric only, max 23 chars) [non-interactive]

--no-agent (optional)

Skip agent creation [non-interactive]

--defaults (optional)

Create a harness project with default settings (this is the default) [non-interactive]

--build <type> (optional)

Build type: CodeZip or Container (default: CodeZip) [non-interactive]

--language <language> (optional)

Target language: Python or TypeScript (default: Python) [non-interactive]

--framework <framework> (optional)

Agent framework (Strands, LangChain_LangGraph, GoogleADK, OpenAIAgents, VercelAI) [non-interactive]

--model-provider <provider> (optional)

Model provider (Bedrock, Anthropic, OpenAI, Gemini) [non-interactive]

--api-key <key> (optional)

API key for non-Bedrock providers [non-interactive]

--memory <option> (optional)

Memory option (none, shortTerm, longAndShortTerm) [non-interactive]

--protocol <protocol> (optional)

Protocol: HTTP, MCP, A2A, AGUI (default: HTTP) [non-interactive]

--type <type> (optional)

Agent type: create or import (default: create) [non-interactive]

--agent-id <id> (optional)

Bedrock Agent ID (required for --type import) [non-interactive]

--agent-alias-id <id> (optional)

Bedrock Agent Alias ID (required for --type import) [non-interactive]

--region <region> (optional)

The AWS Region for Bedrock Agent (required for --type import) [non-interactive]

--network-mode <mode> (optional)

Network mode (PUBLIC, VPC) [non-interactive]

--subnets <ids> (optional)

Comma-separated subnet IDs (required for VPC mode) [non-interactive]

--security-groups <ids> (optional)

Comma-separated security group IDs (required for VPC mode) [non-interactive]

--vpc-id <id> (optional)

VPC ID (required for Container builds with VPC mode) [non-interactive]

--idle-timeout <seconds> (optional)

Idle session timeout in seconds (60-28800) [non-interactive]

--max-lifetime <seconds> (optional)

Max instance lifetime in seconds (60-28800) [non-interactive]

--session-storage-mount-path <path> (optional)

Absolute mount path for session filesystem storage under /mnt (for example, /mnt/data) [non-interactive]

--efs-access-point-arn <arn> (optional)

EFS access point ARN (repeatable, paired with --efs-mount-path) [non-interactive] (default: [])

--efs-mount-path <path> (optional)

EFS mount path (for example, /mnt/tools, paired with --efs-access-point-arn) [non-interactive] (default: [])

--s3-access-point-arn <arn> (optional)

S3 Files access point ARN (repeatable, paired with --s3-mount-path) [non-interactive] (default: [])

--s3-mount-path <path> (optional)

S3 Files mount path (for example, /mnt/datasets, paired with --s3-access-point-arn) [non-interactive] (default: [])

--with-config-bundle (optional)

Create a config bundle wired into the agent template [non-interactive]

--output-dir <dir> (optional)

Output directory (default: current directory) [non-interactive]

--skip-git (optional)

Skip git repository initialization [non-interactive]

--skip-python-setup (optional)

Skip Python virtual environment setup [non-interactive]

--skip-install (optional)

Skip all dependency installation (npm install, uv sync) [non-interactive]

--dry-run (optional)

Preview what would be created without making changes [non-interactive]

--json (optional)

Output as JSON [non-interactive]

--model-id <id> (optional)

Model ID for harness [non-interactive]

--api-key-arn <arn> (optional)

API key ARN for non-Bedrock harness providers [non-interactive]

--api-base <url> (optional)

Base URL for the harness model provider API endpoint (lite_llm) [non-interactive]

--additional-params <json> (optional)

Provider-specific harness params as a JSON object (lite_llm) [non-interactive]

--no-harness-memory (optional)

Disable memory for the harness (this is the default) [non-interactive]

--max-iterations <n> (optional)

Max agent loop iterations (harness) [non-interactive]

--max-tokens <n> (optional)

Max tokens per iteration (harness) [non-interactive]

--timeout <seconds> (optional)

Max execution duration in seconds (harness) [non-interactive]

--truncation-strategy <strategy> (optional)

Truncation strategy: sliding_window or summarization (harness) [non-interactive]

--container <uri-or-path> (optional)

Container image URI or Dockerfile path (harness) [non-interactive]

agentcore deploy

agentcore deploy|dp [options]

Deploy project infrastructure to AWS via CDK.

Parameters

--target <target> (optional)

Deployment target name (default: "default") [non-interactive]

-y, --yes (optional)

Auto-confirm prompts, read credentials from env [non-interactive]

-v, --verbose (optional)

Show resource-level deployment events [non-interactive]

--json (optional)

Output as JSON [non-interactive]

--dry-run (optional)

Preview deployment without deploying [non-interactive]

--diff (optional)

Show CDK diff without deploying [non-interactive]

agentcore dev

agentcore dev|d [options] [prompt]

Launch local dev server, or invoke an agent locally.

Parameters

prompt

Send a prompt to a running dev server [non-interactive]

-p, --port <port> (optional)

Port for development server. Used as-is when set explicitly; the default is offset by the runtime index in multi-runtime projects. (default: "8080")

-r, --runtime <name> (optional)

Runtime to run or invoke (required if multiple runtimes)

-s, --stream (optional)

Stream response when invoking [non-interactive]

-l, --logs (optional)

Run dev server with logs to stdout [non-interactive]

--exec (optional)

Execute a shell command in the running dev container (Container agents only) [non-interactive]

--tool <name> (optional)

MCP tool name (used with "call-tool" prompt) [non-interactive]

--input <json> (optional)

MCP tool arguments as JSON (used with --tool) [non-interactive]

--skip-deploy (optional)

Skip automatic resource deployment before starting dev server

-H, --header <header> (optional)

Custom header to forward to the agent (format: "Name: Value", repeatable) [non-interactive] (default: [])

-b, --no-browser (optional)

Use terminal TUI instead of web-based chat UI

--no-traces (optional)

Disable local OTEL trace collection

agentcore package

agentcore package|pkg [options]

Package agent artifacts without deploying.

Parameters

-d, --directory <path> (optional)

Project directory containing agentcore config

-r, --runtime <name> (optional)

Package only the specified runtime

agentcore export

agentcore export [options] [command]

Export a harness to a Strands runtime agent.

agentcore update

agentcore update [options] [command]

Check for and install CLI updates

Parameters

-c, --check (optional)

Check for updates without installing

agentcore validate

agentcore validate [options]

Validate agentcore/ config files.

Parameters

-d, --directory <path> (optional)

Project directory containing agentcore config

--json (optional)

Output as JSON [non-interactive]

Invocation & Runtime

Auto-generated from @aws/agentcore v0.28.1 — do not edit by hand.

agentcore invoke

agentcore invoke|i [options] [prompt]

Invoke a deployed agent endpoint.

Parameters

prompt

Prompt to send to the agent. Also accepts piped stdin when no prompt is provided and stdin is not a TTY [non-interactive]

--prompt <text> (optional)

Prompt to send to the agent [non-interactive]

--prompt-file <path> (optional)

Read the prompt from a file (for long or structured payloads that exceed shell arg limits) [non-interactive]

--runtime <name> (optional)

Select specific runtime [non-interactive]

--gateway <name> (optional)

Invoke through a gateway [non-interactive]

--gateway-target-name <name> (optional)

HTTP runtime target on the gateway [non-interactive]

--target <name> (optional)

Select deployment target [non-interactive]

--session-id <id> (optional)

Use specific session ID for conversation continuity

--user-id <id> (optional)

User ID for runtime invocation (default: "default-user")

--api-base <url> (optional)

The LiteLLM API base URL override for harness invocations. Available only with lite_llm in non-interactive mode.

--additional-params <json> (optional)

The additional LiteLLM parameters, as a JSON object, for harness invocations. Available only with lite_llm in non-interactive mode.

--payment-user-id <id> (optional)

End-user/wallet-owner identity (defaults to --user-id)

--payment-instrument-id <id> (optional)

Payment instrument (wallet) ID

--payment-session-id <id> (optional)

Payment session ID for budget tracking

--auto-session (optional)

Auto-create/reuse a payment session for testing

--json (optional)

Output as JSON

--stream (optional)

Stream response in real-time

--tool <name> (optional)

MCP tool name (use with "call-tool" prompt)

--input <json> (optional)

MCP tool arguments as JSON (use with --tool)

--exec (optional)

Execute a shell command in the runtime container

--timeout <seconds> (optional)

Timeout in seconds for --exec commands

-H, --header <header> (optional)

Custom header "Name: Value" (repeatable)

--bearer-token <token> (optional)

Bearer token for CUSTOM_JWT auth (bypasses SigV4)

--harness <name> (optional)

Select specific harness to invoke

--harness-arn <arn> (optional)

Invoke a harness by ARN (no project required)

--region <region> (optional)

The AWS Region (required with --harness-arn)

--verbose (optional)

Print verbose streaming JSON events

--model-id <id> (optional)

Override model

--model-provider <provider> (optional)

The model provider. Valid values: bedrock, open_ai, or gemini.

--api-key-arn <arn> (optional)

API key ARN for open_ai/gemini

--tools <tools> (optional)

Override tools (comma-separated)

--allowed-tools <tools> (optional)

Override allowed tools (comma-separated)

--skills <paths> (optional)

Skills (comma-separated paths)

--system-prompt <text> (optional)

Override system prompt

--actor-id <id> (optional)

Override memory actor ID

--max-iterations <n> (optional)

Override max iterations

--max-tokens <n> (optional)

Override max tokens

--harness-timeout <seconds> (optional)

Override timeout seconds

agentcore exec

agentcore exec [options] [command...]

Open an interactive shell or run a one-shot command in a deployed agent container.

Parameters

command

Command to execute (one-shot mode, non-interactive)

--it (optional)

Open an interactive PTY shell session

--runtime <name|arn> (optional)

Target agent name or runtime ARN (skips agent picker)

--harness <name|arn> (optional)

Target harness name or harness ARN (skips agent picker)

--session-id <id> (optional)

Pin to a specific runtime session / VM

--shell-id <id> (optional)

Reconnect to an existing shell

--region <region> (optional)

The AWS Region

--bearer-token <token> (optional)

Bearer token for CUSTOM_JWT authentication (skips SigV4)

--target <name> (optional)

Deployment target name (from agentcore.json)

--timeout <seconds> (optional)

Timeout in seconds for one-shot commands

--json (optional)

Output result as JSON (one-shot mode only, incompatible with --it)

agentcore run

agentcore run [options] [command]

Run evaluations, batch evaluations, or optimization recommendations.

agentcore logs

agentcore logs|l [options] [command]

Stream or search agent runtime logs.

Parameters

--runtime <name> (optional)

Select specific runtime

--since <time> (optional)

Start time — defaults to 1h ago in search mode (for example, "1h", "30m", "2d", ISO 8601)

--until <time> (optional)

End time — defaults to now in search mode (for example, "now", ISO 8601)

--level <level> (optional)

Filter by log level (error, warn, info, debug)

-n, --limit <count> (optional)

Maximum number of log lines to return

--query <text> (optional)

Server-side text filter

--json (optional)

Output as JSON Lines

agentcore traces

agentcore traces|t [options] [command]

View and download agent traces.

agentcore status

agentcore status|s [options]

Show deployed resource details and status.

Parameters

--runtime-id <id> (optional)

Look up a specific runtime by ID

--target <name> (optional)

Select deployment target

--type <type> (optional)

Filter by resource type (agent, runtime-endpoint, memory, credential, gateway, evaluator, online-eval, payment, policy-engine, policy, config-bundle, dataset, knowledge-base, harness)

--state <state> (optional)

Filter by deployment state (deployed, local-only, pending-removal)

--runtime <name> (optional)

Filter to a specific runtime

--name <name> (optional)

Show details for a single resource by name (knowledge-base)

--json (optional)

Output as JSON

agentcore fetch

agentcore fetch [options] [command]

Fetch access info for deployed resources.

agentcore view

agentcore view [options] [command]

View job history and details

Resource Management

Auto-generated from @aws/agentcore v0.28.1 — do not edit by hand.

agentcore add

agentcore add [options] [command] [subcommand]

Add resources to project config.

agentcore remove

agentcore remove [options] [command] [subcommand]

Remove resources from project config.

agentcore import

agentcore import [options] [command]

Import a runtime, memory, or starter toolkit into this project.

Parameters

--source <path> (optional)

Path to the .bedrock_agentcore.yaml configuration file

--target <target> (optional)

Deployment target name (only needed if project has multiple targets)

-y, --yes (optional)

Auto-confirm prompts

Evaluation & Datasets

Auto-generated from @aws/agentcore v0.28.1 — do not edit by hand.

agentcore evals

agentcore evals [options] [command]

View saved eval and batch eval results from past runs.

agentcore batch-evaluations

agentcore batch-evaluations [options] [command] <id>

View batch evaluation jobs and their results.

Parameters

id

Batch evaluation job ID to view

--json (optional)

Output as JSON

agentcore dataset

agentcore dataset [options] [command]

Manage dataset content and versions

Optimization & Config Bundles

Auto-generated from @aws/agentcore v0.28.1 — do not edit by hand.

agentcore config-bundle

agentcore config-bundle|cb [options] [command]

Manage configuration bundles (use bundle name from agentcore.json, not the ID)

agentcore promote

agentcore promote [options] [command]

Promote resources

agentcore archive

agentcore archive [options] [command]

Archive (delete) a batch evaluation or recommendation on the service and clear local history.

Operations & Settings

Auto-generated from @aws/agentcore v0.28.1 — do not edit by hand.

agentcore pause

agentcore pause [options] [command]

Pause a deployed resource (online eval config, A/B test).

agentcore resume

agentcore resume [options] [command]

Resume a paused resource (online eval config, A/B test).

agentcore stop

agentcore stop [options] [command]

Stop a running batch evaluation or A/B test.

agentcore config

agentcore config [options] [key] [value]

Adjust global configuration settings such as telemetry opt-out status

Parameters

key

Config key in dot notation (for example, telemetry.enabled)

value

Value to set

agentcore telemetry

agentcore telemetry [options] [command]

Manage anonymous usage analytics preferences.

agentcore feedback

agentcore feedback [options] [message]

Send feedback about the AgentCore CLI to the team.

Parameters

message

Feedback message [non-interactive]

--screenshot <path> (optional)

Path to a PNG or JPG screenshot (max 100MB) [non-interactive]

--json (optional)

Output result as JSON [non-interactive]