Skip to content

Commit 9c7f143

Browse files
jesseturner21jesseturner21
authored
fix: improve CLI UX — memory docs, standardize flags, fix deploy alias (#703)
- Document --memory shorthand mapping (none/shortTerm/longAndShortTerm) in memory.md with actual strategy configs and default namespaces - Add cross-references from commands.md --memory flag descriptions - Standardize max-results flags: logs now uses -n/--limit (matching traces list and evals history) instead of -n/--lines - Change deploy alias from 'p' to 'dp' to avoid confusion with 'package'/'publish'
1 parent c123d2f commit 9c7f143

7 files changed

Lines changed: 71 additions & 54 deletions

File tree

‎docs/commands.md‎

Lines changed: 47 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Run `agentcore` without arguments to launch the interactive TUI. Flags marked `[
99

1010
| Command | Alias |
1111
| --------- | ----- |
12-
| `deploy` | `p` |
12+
| `deploy` | `dp` |
1313
| `dev` | `d` |
1414
| `invoke` | `i` |
1515
| `status` | `s` |
@@ -65,30 +65,30 @@ agentcore create \
6565
--memory none
6666
```
6767

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

9393
### deploy
9494

@@ -193,26 +193,26 @@ agentcore add agent \
193193
--memory none
194194
```
195195

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

217217
### add memory
218218

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

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

‎docs/memory.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,23 @@ async def invoke(payload, context):
149149
agentcore deploy
150150
```
151151

152+
## `--memory` Shorthand Mapping
153+
154+
The `create` and `add agent` commands accept a `--memory` flag with one of three shorthand values. Each maps to a
155+
specific memory configuration:
156+
157+
| Shorthand | Strategies Created |
158+
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
159+
| `none` | No memory resource created |
160+
| `shortTerm` | Memory with no strategies (session context via event expiry only, default 30 days) |
161+
| `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}`) |
162+
163+
**Short-term memory** provides basic conversation context within a session — events are stored and expire after the
164+
configured duration, but no long-term extraction or search is performed.
165+
166+
**Long-and-short-term memory** adds persistent strategies that extract facts, preferences, summaries, and episodes from
167+
conversations, enabling cross-session recall via semantic search.
168+
152169
## Memory Strategies
153170

154171
| Strategy | Description |

‎src/cli/commands/deploy/command.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@ async function handleDeployCLI(options: DeployOptions): Promise<void> {
130130
export const registerDeploy = (program: Command) => {
131131
program
132132
.command('deploy')
133-
.alias('p')
133+
.alias('dp')
134134
.description(COMMAND_DESCRIPTIONS.deploy)
135135
.option('--target <target>', 'Deployment target name (default: "default") [non-interactive]')
136136
.option('-y, --yes', 'Auto-confirm prompts, read credentials from env [non-interactive]')

‎src/cli/commands/logs/action.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ export async function handleLogs(options: LogsOptions): Promise<LogsResult> {
110110
if (mode === 'search') {
111111
const startTimeMs = options.since ? parseTimeString(options.since) : Date.now() - 3_600_000;
112112
const endTimeMs = options.until ? parseTimeString(options.until) : Date.now();
113-
const limit = options.lines ? parseInt(options.lines, 10) : undefined;
113+
const limit = options.limit ? parseInt(options.limit, 10) : undefined;
114114

115115
for await (const event of searchLogs({
116116
logGroupName: agentContext.logGroupName,

‎src/cli/commands/logs/command.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ export const registerLogs = (program: Command) => {
2424
.option('--since <time>', 'Start time — defaults to 1h ago in search mode (e.g. "1h", "30m", "2d", ISO 8601)')
2525
.option('--until <time>', 'End time — defaults to now in search mode (e.g. "now", ISO 8601)')
2626
.option('--level <level>', 'Filter by log level (error, warn, info, debug)')
27-
.option('-n, --lines <count>', 'Maximum number of log lines to return')
27+
.option('-n, --limit <count>', 'Maximum number of log lines to return')
2828
.option('--query <text>', 'Server-side text filter')
2929
.option('--json', 'Output as JSON Lines')
3030
.action(async (cliOptions: LogsOptions) => {
@@ -49,7 +49,7 @@ export const registerLogs = (program: Command) => {
4949
.option('-a, --agent <name>', 'Select specific agent')
5050
.option('--since <time>', 'Start time (e.g. "1h", "30m", "2d", ISO 8601)')
5151
.option('--until <time>', 'End time (e.g. "now", ISO 8601)')
52-
.option('-n, --lines <count>', 'Maximum number of log lines')
52+
.option('-n, --limit <count>', 'Maximum number of log lines')
5353
.option('-f, --follow', 'Stream logs in real-time (default when no --since/--until)')
5454
.option('--json', 'Output as JSON Lines')
5555
.action(async (cliOptions: LogsEvalOptions) => {

‎src/cli/commands/logs/types.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ export interface LogsOptions {
33
since?: string;
44
until?: string;
55
level?: string;
6-
lines?: string;
6+
limit?: string;
77
query?: string;
88
json?: boolean;
99
}

‎src/cli/operations/eval/logs-eval.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ export interface LogsEvalOptions {
88
agent?: string;
99
since?: string;
1010
until?: string;
11-
lines?: string;
11+
limit?: string;
1212
json?: boolean;
1313
follow?: boolean;
1414
}
@@ -109,7 +109,7 @@ export async function handleLogsEval(options: LogsEvalOptions): Promise<LogsEval
109109
if (!isFollow) {
110110
const startTimeMs = options.since ? parseTimeString(options.since) : Date.now() - 3_600_000;
111111
const endTimeMs = options.until ? parseTimeString(options.until) : Date.now();
112-
const limit = options.lines ? parseInt(options.lines, 10) : undefined;
112+
const limit = options.limit ? parseInt(options.limit, 10) : undefined;
113113

114114
try {
115115
for await (const event of searchLogs({

0 commit comments

Comments
 (0)