Skip to content

fix: improve CLI UX — memory docs, standardize flags, fix deploy alias #703

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jesseturner21 merged 1 commit into from
Mar 27, 2026
Merged

fix: improve CLI UX — memory docs, standardize flags, fix deploy alias #703

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 47 additions & 47 deletions docs/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Run `agentcore` without arguments to launch the interactive TUI. Flags marked `[

| Command | Alias |
| --------- | ----- |
| `deploy` | `p` |
| `deploy` | `dp` |
| `dev` | `d` |
| `invoke` | `i` |
| `status` | `s` |
Expand Down Expand Up @@ -65,30 +65,30 @@ agentcore create \
--memory none
```

| Flag | Description |
| ------------------------- | -------------------------------------------------------------------------------- |
| `--name <name>` | Project name (alphanumeric, starts with letter, max 23 chars) |
| `--defaults` | Use defaults (Python, Strands, Bedrock, no memory) |
| `--no-agent` | Skip agent creation |
| `--type <type>` | `create` (default) or `import` |
| `--language <lang>` | `Python` (default) |
| `--framework <fw>` | `Strands`, `LangChain_LangGraph`, `CrewAI`, `GoogleADK`, `OpenAIAgents` |
| `--model-provider <p>` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` |
| `--build <type>` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) |
| `--api-key <key>` | API key for non-Bedrock providers |
| `--memory <opt>` | `none`, `shortTerm`, `longAndShortTerm` |
| `--protocol <protocol>` | `HTTP` (default), `MCP`, `A2A` |
| `--network-mode <mode>` | `PUBLIC` (default) or `VPC` |
| `--subnets <ids>` | Comma-separated subnet IDs (required for VPC mode) |
| `--security-groups <ids>` | Comma-separated security group IDs (required for VPC mode) |
| `--agent-id <id>` | Bedrock Agent ID (import only) |
| `--agent-alias-id <id>` | Bedrock Agent Alias ID (import only) |
| `--region <region>` | AWS region for Bedrock Agent (import only) |
| `--output-dir <dir>` | Output directory |
| `--skip-git` | Skip git initialization |
| `--skip-python-setup` | Skip venv setup |
| `--dry-run` | Preview without creating |
| `--json` | JSON output |
| Flag | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `--name <name>` | Project name (alphanumeric, starts with letter, max 23 chars) |
| `--defaults` | Use defaults (Python, Strands, Bedrock, no memory) |
| `--no-agent` | Skip agent creation |
| `--type <type>` | `create` (default) or `import` |
| `--language <lang>` | `Python` (default) |
| `--framework <fw>` | `Strands`, `LangChain_LangGraph`, `CrewAI`, `GoogleADK`, `OpenAIAgents` |
| `--model-provider <p>` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` |
| `--build <type>` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) |
| `--api-key <key>` | API key for non-Bedrock providers |
| `--memory <opt>` | `none`, `shortTerm`, `longAndShortTerm` (see [Memory Shorthand Mapping](memory.md#--memory-shorthand-mapping)) |
| `--protocol <protocol>` | `HTTP` (default), `MCP`, `A2A` |
| `--network-mode <mode>` | `PUBLIC` (default) or `VPC` |
| `--subnets <ids>` | Comma-separated subnet IDs (required for VPC mode) |
| `--security-groups <ids>` | Comma-separated security group IDs (required for VPC mode) |
| `--agent-id <id>` | Bedrock Agent ID (import only) |
| `--agent-alias-id <id>` | Bedrock Agent Alias ID (import only) |
| `--region <region>` | AWS region for Bedrock Agent (import only) |
| `--output-dir <dir>` | Output directory |
| `--skip-git` | Skip git initialization |
| `--skip-python-setup` | Skip venv setup |
| `--dry-run` | Preview without creating |
| `--json` | JSON output |

### deploy

Expand Down Expand Up @@ -193,26 +193,26 @@ agentcore add agent \
--memory none
```

| Flag | Description |
| ------------------------- | -------------------------------------------------------------------------------- |
| `--name <name>` | Agent name (alphanumeric, starts with letter, max 64 chars) |
| `--type <type>` | `create` (default), `byo`, or `import` |
| `--build <type>` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) |
| `--language <lang>` | `Python` (create); `Python`, `TypeScript`, `Other` (BYO) |
| `--framework <fw>` | `Strands`, `LangChain_LangGraph`, `CrewAI`, `GoogleADK`, `OpenAIAgents` |
| `--model-provider <p>` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` |
| `--api-key <key>` | API key for non-Bedrock providers |
| `--memory <opt>` | `none`, `shortTerm`, `longAndShortTerm` (create and import) |
| `--protocol <protocol>` | `HTTP` (default), `MCP`, `A2A` |
| `--code-location <path>` | Path to existing code (BYO only) |
| `--entrypoint <file>` | Entry file relative to code-location (BYO, default: `main.py`) |
| `--network-mode <mode>` | `PUBLIC` (default) or `VPC` |
| `--subnets <ids>` | Comma-separated subnet IDs (required for VPC mode) |
| `--security-groups <ids>` | Comma-separated security group IDs (required for VPC mode) |
| `--agent-id <id>` | Bedrock Agent ID (import only) |
| `--agent-alias-id <id>` | Bedrock Agent Alias ID (import only) |
| `--region <region>` | AWS region for Bedrock Agent (import only) |
| `--json` | JSON output |
| Flag | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--name <name>` | Agent name (alphanumeric, starts with letter, max 64 chars) |
| `--type <type>` | `create` (default), `byo`, or `import` |
| `--build <type>` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) |
| `--language <lang>` | `Python` (create); `Python`, `TypeScript`, `Other` (BYO) |
| `--framework <fw>` | `Strands`, `LangChain_LangGraph`, `CrewAI`, `GoogleADK`, `OpenAIAgents` |
| `--model-provider <p>` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` |
| `--api-key <key>` | API key for non-Bedrock providers |
| `--memory <opt>` | `none`, `shortTerm`, `longAndShortTerm` (create and import; see [Memory Shorthand Mapping](memory.md#--memory-shorthand-mapping)) |
| `--protocol <protocol>` | `HTTP` (default), `MCP`, `A2A` |
| `--code-location <path>` | Path to existing code (BYO only) |
| `--entrypoint <file>` | Entry file relative to code-location (BYO, default: `main.py`) |
| `--network-mode <mode>` | `PUBLIC` (default) or `VPC` |
| `--subnets <ids>` | Comma-separated subnet IDs (required for VPC mode) |
| `--security-groups <ids>` | Comma-separated security group IDs (required for VPC mode) |
| `--agent-id <id>` | Bedrock Agent ID (import only) |
| `--agent-alias-id <id>` | Bedrock Agent Alias ID (import only) |
| `--region <region>` | AWS region for Bedrock Agent (import only) |
| `--json` | JSON output |

### add memory

Expand Down Expand Up @@ -542,7 +542,7 @@ agentcore logs --json # JSON Lines output
| `--since <time>` | Start time (defaults to 1h ago in search mode; e.g. `1h`, `30m`, `2d`, ISO 8601) |
| `--until <time>` | End time (defaults to now in search mode; e.g. `now`, ISO 8601) |
| `--level <level>` | Filter by log level: `error`, `warn`, `info`, `debug` |
| `-n, --lines <n>` | Maximum number of log lines to return |
| `-n, --limit <n>` | Maximum number of log lines to return |
| `--query <text>` | Server-side text filter |
| `--json` | Output as JSON Lines |

Expand Down Expand Up @@ -675,7 +675,7 @@ agentcore logs evals --follow --json
| `-a, --agent <name>` | Filter by agent |
| `--since <time>` | Start time (e.g. `1h`, `30m`, `2d`, ISO 8601) |
| `--until <time>` | End time |
| `-n, --lines <count>` | Maximum log lines |
| `-n, --limit <count>` | Maximum log lines |
| `-f, --follow` | Stream in real-time |
| `--json` | JSON Lines output |

Expand Down
17 changes: 17 additions & 0 deletions docs/memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,23 @@ async def invoke(payload, context):
agentcore deploy
```

## `--memory` Shorthand Mapping

The `create` and `add agent` commands accept a `--memory` flag with one of three shorthand values. Each maps to a
specific memory configuration:

| Shorthand | Strategies Created |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none` | No memory resource created |
| `shortTerm` | Memory with no strategies (session context via event expiry only, default 30 days) |
| `longAndShortTerm` | Memory with four strategies: `SEMANTIC` (`/users/{actorId}/facts`), `USER_PREFERENCE` (`/users/{actorId}/preferences`), `SUMMARIZATION` (`/summaries/{actorId}/{sessionId}`), `EPISODIC` (`/episodes/{actorId}/{sessionId}`, reflection: `/episodes/{actorId}`) |

**Short-term memory** provides basic conversation context within a session — events are stored and expire after the
configured duration, but no long-term extraction or search is performed.

**Long-and-short-term memory** adds persistent strategies that extract facts, preferences, summaries, and episodes from
conversations, enabling cross-session recall via semantic search.

## Memory Strategies

| Strategy | Description |
Expand Down
2 changes: 1 addition & 1 deletion src/cli/commands/deploy/command.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ async function handleDeployCLI(options: DeployOptions): Promise<void> {
export const registerDeploy = (program: Command) => {
program
.command('deploy')
.alias('p')
.alias('dp')
.description(COMMAND_DESCRIPTIONS.deploy)
.option('--target <target>', 'Deployment target name (default: "default") [non-interactive]')
.option('-y, --yes', 'Auto-confirm prompts, read credentials from env [non-interactive]')
Expand Down
2 changes: 1 addition & 1 deletion src/cli/commands/logs/action.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ export async function handleLogs(options: LogsOptions): Promise<LogsResult> {
if (mode === 'search') {
const startTimeMs = options.since ? parseTimeString(options.since) : Date.now() - 3_600_000;
const endTimeMs = options.until ? parseTimeString(options.until) : Date.now();
const limit = options.lines ? parseInt(options.lines, 10) : undefined;
const limit = options.limit ? parseInt(options.limit, 10) : undefined;

for await (const event of searchLogs({
logGroupName: agentContext.logGroupName,
Expand Down
4 changes: 2 additions & 2 deletions src/cli/commands/logs/command.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ export const registerLogs = (program: Command) => {
.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)')
.option('-n, --lines <count>', 'Maximum number of log lines to return')
.option('-n, --limit <count>', 'Maximum number of log lines to return')
.option('--query <text>', 'Server-side text filter')
.option('--json', 'Output as JSON Lines')
.action(async (cliOptions: LogsOptions) => {
Expand All @@ -49,7 +49,7 @@ export const registerLogs = (program: Command) => {
.option('-a, --agent <name>', 'Select specific agent')
.option('--since <time>', 'Start time (e.g. "1h", "30m", "2d", ISO 8601)')
.option('--until <time>', 'End time (e.g. "now", ISO 8601)')
.option('-n, --lines <count>', 'Maximum number of log lines')
.option('-n, --limit <count>', 'Maximum number of log lines')
.option('-f, --follow', 'Stream logs in real-time (default when no --since/--until)')
.option('--json', 'Output as JSON Lines')
.action(async (cliOptions: LogsEvalOptions) => {
Expand Down
2 changes: 1 addition & 1 deletion src/cli/commands/logs/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ export interface LogsOptions {
since?: string;
until?: string;
level?: string;
lines?: string;
limit?: string;
query?: string;
json?: boolean;
}
4 changes: 2 additions & 2 deletions src/cli/operations/eval/logs-eval.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ export interface LogsEvalOptions {
agent?: string;
since?: string;
until?: string;
lines?: string;
limit?: string;
json?: boolean;
follow?: boolean;
}
Expand Down Expand Up @@ -109,7 +109,7 @@ export async function handleLogsEval(options: LogsEvalOptions): Promise<LogsEval
if (!isFollow) {
const startTimeMs = options.since ? parseTimeString(options.since) : Date.now() - 3_600_000;
const endTimeMs = options.until ? parseTimeString(options.until) : Date.now();
const limit = options.lines ? parseInt(options.lines, 10) : undefined;
const limit = options.limit ? parseInt(options.limit, 10) : undefined;

try {
for await (const event of searchLogs({
Expand Down
Loading