Mastering Amazon Bedrock CLIs: AWS CLI, Model Operations, and AgentCore

On 29 October 2026 this page was rechecked against AWS CLI 2.39.1 and AgentCore CLI 1.0.1 (agentcore --version). The first version, on 11 October, was written against 2.37.12 and 0.30.0. AWS announced AgentCore CLI 1.0 as generally available on 28 October, and about a third of the agentcore commands on the old page no longer work. There is still no single official executable named bedrock-cli. aws help lists eight Bedrock-related namespaces. agentcore --help lists a separate project and resource CLI. Commands that would call a model, create a runtime, or read production logs were not run.

Two published figures from this site, not new measurements: a support-style AgentCore sketch at about $791 per month for 50K sessions is in the AgentCore vs Quick decision guide. Gateway server-side tool round-trip from about 180 ms to about 95 ms on a B2B CRM assistant is in the Gateway post. Use them as cost and latency context. They are not a promise for your catalog agent.

We recommend the agentcore CLI for project create, local dev, deploy, invoke, logs, traces, and evals, and the AWS CLI when you need an API operation the project CLI does not wrap. The trade-off: agentcore deploy hides the CDK stack that aws bedrock-agentcore-control shows you resource by resource. When a deploy fails, you still need the AWS CLI identity check and the control-plane get-* call.

What changed in AgentCore CLI 1.0

Install is npm install -g @aws/agentcore. It needs Node.js 20.12 or later, and Python templates also need uv. The Python Bedrock AgentCore Starter Toolkit also installs a command named agentcore. Uninstall it, or which agentcore will tell you that you are reading the wrong help.

From the breaking-changes guide and 1.0.1 help:

Also removed: import, fetch, promote ab-test, add knowledge-base, add capacity-provider, and run ingest.

The interfaces, and which plane they talk to

aws bedrock-data-automation and aws bedrock-data-automation-runtime also appear in aws help on this build. They are a different product surface. This article does not teach them.

Identity and region are the AWS CLI checks. Run them before any command in the tables below.

aws sts get-caller-identity --no-cli-pager
aws configure get region

A wrong region is a wrong model list. Model access is regional. agentcore resolves its own region in this order: --region, AWS_REGION, AWS_DEFAULT_REGION, the active profile, then us-east-1. That last fallback is how a sandbox test ends up in the wrong region.

Discovery on each CLI

AWS CLI, read-only, no network beyond whatever help does locally:

aws bedrock help
aws bedrock-runtime help
aws bedrock-agentcore-control help
aws bedrock-agentcore help

AgentCore CLI, observed on 1.0.1:

agentcore --help
agentcore create --help
agentcore dev --help
agentcore invoke --help
agentcore eval --help
agentcore runtime --help
agentcore migrate --help

agentcore --help on 1.0.1 groups commands three ways. Project: create, add, remove, dev, build, deploy, invoke, status, logs, traces, export, migrate. Resources: harness, runtime, gateway, identity, memory, eval, payment. Settings: feedback, config, update. Global flags are --region, --json, and --debug. Run agentcore with no arguments and you get an interactive terminal UI. Pass flags and it stays scriptable.

One quirk on 1.0.1: --help on a third-level command such as agentcore logs runtime --help printed the top-level help, not the subcommand’s flags. Read the CLI reference for those flags. If your version differs, trust agentcore --help over this page.

Models, tokens, and guardrails

These AWS CLI operations were listed by help on 2.39.1. They were not executed.

converse requires --model-id. The help text says that id can be a foundation model or an inference profile. Read aws bedrock-runtime converse help for the body shape. Do not reuse a JSON body from another provider. Parameter names are model-specific.

create-provisioned-model-throughput and create-foundation-model-agreement are remote mutation. Provisioned throughput is potential cost impact that continues until you delete it. delete-provisioned-model-throughput is the rollback, and it is also a change. List and get first.

Guardrail writes (create-guardrail, update-guardrail) change policy for every caller that uses that guardrail id. Remote mutation. Get the current guardrail and save the JSON before you update it.

Knowledge bases and Agents Classic

aws bedrock-agent help can list and get knowledge bases, data sources, and ingestion jobs (list-knowledge-bases, get-knowledge-base, list-data-sources, get-ingestion-job). Those are control-plane reads when you only list or get. Starting an ingestion job is a mutation and can incur embedding cost.

aws bedrock-agent-runtime help on this CLI lists retrieve and retrieve-and-generate. Retrieval is a data-plane call. It can return customer content. Treat the output as sensitive.

The same help text says Agents Classic is no longer open to new customers. create-agent still appears for accounts that are allowed to call it. Do not use it as the template for a new e-commerce support agent. If you operate an existing Classic agent, get-agent and list-agents are the inspection commands. Invocation shapes change. Read aws bedrock-agent-runtime help on your CLI instead of an old invoke-agent snippet. On 2.39.1 that exact command name was still not in the available-commands list.

AgentCore control plane and data plane

Control plane (aws bedrock-agentcore-control), from help, not run:

create-agent-runtime help marks --agent-runtime-name, --agent-runtime-artifact, and --role-arn as required. The artifact structure is in that help page. Filling it in creates infrastructure. Do it in a sandbox account after sts get-caller-identity.

Data plane (aws bedrock-agentcore):

invoke-agent-runtime is how you hit a deployed runtime without the agentcore wrapper. Since 1.0, agentcore runtime get and agentcore runtime list cover the common reads too. The AWS CLI is still what you use when you are debugging permissions and the project CLI hides the error.

The agentcore binary

Observed subcommands and flags on 1.0.1. Not a deploy.

agentcore create --name NAME --template TEMPLATE scaffolds a project. The 1.0.1 template list: agent-python-strands, agent-python-strands-container, agent-python-langchain, agent-python-minimal, agent-typescript-strands, agent-typescript-vercel, a2a-python-strands, agui-python-strands, mcp-python-fastmcp, environment-python-bma (Bedrock Managed Agents), and the default empty. The 0.x GoogleADK and OpenAIAgents frameworks have no 1.0 template. --skip-install and --skip-git keep it from running npm install, uv sync, or git init. Local change.

agentcore add runtime and agentcore add harness add resources to the project config. agentcore remove takes them out. Local change until the next deploy.

agentcore dev runs project agents locally. --mode headless is the default. --mode browser opens the Agent Inspector web UI. --port and --no-traces apply to runtimes. For a harness, dev deploys to the default target unless you pass --skip-deploy. That deploy is remote mutation and potential cost impact. Watch the first lines of output for account and region.

agentcore build builds the deployable artifacts. Local change.

agentcore deploy builds and deploys to an AWS target from aws-targets.json. The default target is created from your current account and region on first deploy. It no longer asks you to confirm. --yes only confirms tearing down a target’s stack when the project declares nothing. Remote mutation and potential cost impact. To see the change first, run npm run cdk -- diff inside agentcore/cdk.

agentcore invoke needs --runtime, --harness, or --gateway. Each takes a project name, a resource ID, or an ARN, so you can invoke an agent this project never created. Runtimes take --payload. Harnesses take --prompt. --local hits the dev server. --session-id continues a session. --output-file keeps a long reply out of the terminal scrollback. The payload can contain customer data. The reply can too.

agentcore status shows deployed resources for a target. Read-only relative to the agent, though it calls AWS.

agentcore logs runtime and agentcore logs harness stream or search logs. agentcore traces runtime and agentcore traces harness read traces. The same reads exist under the resource groups, for example agentcore runtime logs. Logs are production data. Traces show tool calls. A tool call that refunded an order is an audit record. Store it. Do not post it raw.

agentcore eval holds evaluators, online evaluation configs, datasets, batch-evaluation, ondemand, config bundles, A/B tests, and recommendations. Runs spend model tokens. Potential cost impact.

agentcore export harness converts a managed harness into a code-defined harness with the Strands Harness SDK, creating a project if needed. It writes files. Local change.

agentcore migrate converts a 0.x project and keeps its deployed resources. --target picks one target when the project deploys to several. It asks before it applies changes unless you pass --yes. Local change, and the next deploy is a remote mutation.

The resource groups work without a project. agentcore runtime get, runtime list, harness get, and harness list are reads. runtime shell, runtime exec, harness shell, and harness exec run commands inside a deployed agent’s environment. Treat those as production access. harness create, update, and delete are remote mutation. agentcore identity manages API key, OAuth2, and payment credential providers. That is where a model provider key belongs.

Scenario: a support agent retrieves bad product data or calls the wrong tool

1. aws sts get-caller-identity and the region. Confirm the sandbox or the production account out loud.
2. agentcore status and, if you need the API record, agentcore runtime get or aws bedrock-agentcore-control get-agent-runtime / get-harness with the id from status. Help lists the id flags. Do not guess them.
3. agentcore logs runtime (or logs harness) with --json, then agentcore traces runtime. Find the turn where retrieval returned the wrong SKU or the tool name was not on the allow list.
4. If the failure is AccessDenied, the missing action is in the error. Fix the role. Do not attach administrator to the runtime role.
5. If retrieval is empty, inspect the knowledge base or gateway target with a get command. A sync or ingestion job that failed is a control-plane fact, not a prompt problem.
6. Diff the fix with npm run cdk -- diff in agentcore/cdk, deploy to a sandbox target, then invoke with a fixed question whose answer you already know.
7. Re-run the eval set (agentcore eval ondemand on the test sessions, or a batch evaluation you already created) before you call production healthy.

Refunds, order edits, and payments stay behind a human approval step. The human-in-the-loop post is the product rule. A CLI invoke that passes is not that approval.

IAM, cost, and output limits

Least privilege means the runtime role can call the model and the tools you named, and cannot s3:DeleteBucket or change orders unless a reviewed tool does so. Test with iam simulate-principal-policy from the AWS CLI article when you are unsure.

Token and latency limits are model-specific. count-tokens is the CLI check when the operation accepts your payload. A 400 from converse that says the input is too long is the enforcement. Truncating customer text silently is a product bug. Log the refusal.

Timeouts and retries belong in the application. The CLI is a single call. A shell loop that retries invoke-model without a cap is a bill.

Region: list models in the region you will deploy. A model id from another region fails or routes differently when you use an inference profile. Read get-inference-profile before you hard-code an id an agent suggested.

Working with a coding agent

Ask the coding agent to run sts get-caller-identity, agentcore --version, and the CDK diff. Ask it to show agentcore runtime get or the control-plane get, not to create a runtime, until you have named the account. If its script still calls agentcore validate or deploy -y, it learned from 0.x docs. Refuse API keys on the command line, refuse runtime exec against production, and refuse delete-memory-record, harness delete, or delete-agent-runtime without a read of what will be removed. After deploy, you run agentcore status and one eval question yourself.

Coding-agent CLIs are the next article. They are not this runtime.

Five labs

1. Run check-clis.sh. Record both versions. If agentcore=absent, install with npm install -g @aws/agentcore and re-run. If you see warn=, upgrade and run agentcore migrate in each existing project.
2. aws bedrock help and write down one control-plane read and one data-plane command from aws bedrock-runtime help.
3. In a sandbox, aws bedrock list-foundation-models --no-cli-pager and confirm the region. Read-only. Stop if the account is production.
4. agentcore create --name LabProject --template agent-python-strands --skip-git in an empty directory you can delete. Local change. Do not pass a production API key anywhere.
5. In that project, npm run cdk -- diff inside agentcore/cdk. Expected: the stack it would create, or a specific config error. Fix the config. Do not deploy until lab 3’s account is the one you intend.

Progression: name the binary, list models in the right region, diff a project, invoke in a sandbox, then trace one tool call.

What this post does not cover

Full AgentCore architecture, pricing math beyond the two cited posts, payments, and Data Automation. Model choice and harness design stay in the production guide linked above. This page will drift when agentcore --help changes. The version pin is 1.0.1.

What to do this week

1. Run the version script and save the output next to your runbook.
2. Search your repos and CI for agentcore validate, agentcore package, deploy -y, and bedrock-agent create-agent. The first three are 0.x. The last is Classic.
3. List every policy attachment that relied on LOG_ONLY before you migrate.
4. Put sts get-caller-identity in front of any deploy script the coding agent generated.
5. Pick one support question with a known SKU and decide how you will eval it before the next deploy.

Quick reference

You should be able to name which binary you are using, refuse Agents Classic for a new agent, spot a 0.x command in a script, and separate a control-plane get from an invoke that spends money.

Further reading

• AgentCore CLI 1.0 announcement
• AgentCore CLI reference
• Get started with the AgentCore CLI
• Migrate from AgentCore CLI 0.x and breaking changes
• AWS CLI bedrock
• bedrock-runtime
• bedrock-agent
• bedrock-agentcore
• bedrock-agentcore-control
• AgentCore developer guide
• agentcore-cli on GitHub
• Series: Git, Linux, AWS CLI, Docker, Kubernetes, AI agent tools

Contact us or start at AI agents if the next step is a scoped support or catalog agent, not another CLI flag. The field guide is eCommerce AI agents. We are an AWS Select Tier Services Partner. That is not an Agentic AI Competency.

Frequently asked questions