CLI And Commands

Purpose and Scope

The CLI command surface is the command-line counterpart to the generated SDK resources: it lets an operator invoke Anthropic API actions from a shell using named commands, flags, and API-key authentication instead of writing TypeScript. In the official CLI docs, beta file operations appear as commands such as ant beta:files upload, ant beta:files list, ant beta:files delete, and ant beta:files download, each mapping to a REST route and a set of flags. This page explains how to read those commands as first-class API primitives and how they relate to the TypeScript SDK's generated beta resources. Sources: bin/migration-config.json, src/resources/beta/index.ts

A command is not just a shortcut for a request. It is a stable user workflow boundary: the command name identifies the resource group, flags represent path, query, body, or header parameters, and the response shape follows the API object returned by the same underlying resource family. For example, the file upload CLI command accepts a --file body parameter and an optional --beta header parameter, while delete and download commands use --file-id as the path parameter. The SDK source evidence shows the same generated style for beta resource groups: exported classes, parameter types, response types, and cursor page types are grouped by domain. Sources: src/resources/beta/index.ts, src/resources/beta/messages/index.ts

Relevant Source Files

bin/migration-config.json - Contains generated migration metadata for command-like SDK method signatures, including how beta environment work methods changed path parameters and option placement.
src/resources/beta/agents/index.ts - Re-exports beta Managed Agents classes and types, including built-in agent toolset input types for bash, edit, glob, grep, read, and write operations.
src/resources/beta/environments/index.ts - Re-exports beta environment resources and the Work resource with retrieve, update, list, ack, heartbeat, poll, stats, and stop parameter types.
src/resources/beta/index.ts - Aggregates the beta namespace, beta error types, deployment resources, agent resources, and other generated beta exports under the SDK's public API surface.
src/resources/beta/memory-stores/index.ts - Re-exports memory stores, memories, memory versions, precondition types, conflict types, and related page cursor contracts.
src/resources/beta/messages/index.ts - Re-exports beta messages, beta message batches, and a large set of beta message content, tool, thinking, citation, container, and code-execution types.

Core Primitives

The primary primitive is the command itself. In the official CLI syntax, commands use a product-oriented namespace such as beta:files followed by an action like upload, list, delete, or download. A command action corresponds to an API operation, while flags carry parameters. The --api-key flag authenticates the command, --beta selects beta versions where required, and resource identifiers such as --file-id bind path parameters. Treat these flags the way you would treat SDK method arguments: they are part of the contract, and changing their values changes the request sent to the API.

The second primitive is the generated resource namespace. In the TypeScript SDK, beta resources are surfaced through generated exports rather than handwritten command strings. src/resources/beta/index.ts gathers the beta API family, including Agents, beta error classes and types, deployment run resources, deployment resources, and many related Managed Agents shapes. The narrower index files follow the same pattern: they expose a resource class plus request parameter types, response object types, and page cursor types. This makes the command model and SDK model complementary: shell users think in commands and flags, while TypeScript users think in resource methods and typed parameter objects. Sources: src/resources/beta/index.ts, src/resources/beta/agents/index.ts

The third primitive is a managed operation, which is visible most clearly in the environments work surface. The environment index exports Work along with parameter types for WorkRetrieveParams, WorkUpdateParams, WorkListParams, WorkAckParams, WorkHeartbeatParams, WorkPollParams, WorkStatsParams, and WorkStopParams. These names describe a worker-style lifecycle: locate work, claim or acknowledge it, keep it alive with heartbeats, update or stop it, and inspect queue state. When designing automation around CLI commands, use the same lifecycle vocabulary so shell scripts and SDK workers remain aligned. Sources: src/resources/beta/environments/index.ts, bin/migration-config.json

System-to-Code Mapping

User-facing concept	CLI or SDK expression	Source-backed SDK surface
Beta command namespace	`ant beta:<resource> <action>`	`Beta` namespace and exported beta resource groups in `src/resources/beta/index.ts`
File command flags	`--file`, `--file-id`, `--beta`, `--api-key`	Same generated parameter-pattern idea used by beta resource parameter types
Managed agent tool commands	Shell-like agent tool operations	`BetaManagedAgentsAgentToolset20260401BashInput`, `EditInput`, `GlobInput`, `GrepInput`, `ReadInput`, and `WriteInput` in `src/resources/beta/agents/index.ts`
Environment work lifecycle	retrieve, update, ack, heartbeat, poll, stats, stop	`Work*Params` exports in `src/resources/beta/environments/index.ts`
Long-running memory state	create, retrieve, update, list, delete, archive, redact	memory store, memory, and memory version parameter types in `src/resources/beta/memory-stores/index.ts`
Message automation	batch creation, retrieval, cancellation, deletion, results	`Batches` and `Batch*Params` exports in `src/resources/beta/messages/index.ts`

Command Execution Flow

A shell command begins with command selection. The user chooses a namespace and action, such as ant beta:files upload, then supplies authentication and operation flags. The official docs identify each command's HTTP method and route, so the command can be read as a documented API call: upload uses POST /v1/files, list uses GET /v1/files, delete uses DELETE /v1/files/{file_id}, and download uses GET /v1/files/{file_id}/content. This route mapping is useful when debugging, because it tells you whether a flag is expected to become a body field, path segment, query parameter, or header.

After parameters are parsed, the command produces an API response object or file content. Upload returns file metadata including id, created_at, filename, mime_type, size_bytes, type, and optional scope information. Delete returns a deleted-file object with an id and type. Download returns file content to a path-oriented result. These response contracts should be treated with the same care as SDK return types: scripts should preserve identifiers for later commands, check object type values when branching, and avoid assuming ID length or format because the official docs state those may change over time.

For Managed Agents and environment automation, the same flow extends beyond files. bin/migration-config.json shows generated migration metadata for beta.environments.work methods, including retrieve, update, ack, heartbeat, and stop. The current signatures use work_id as the path parameter plus params and options, while older signatures included environment_id before work_id. That is an important command-design signal: automation should bind to the current operation identifier and avoid carrying obsolete path arguments forward when updating scripts or SDK calls. Sources: bin/migration-config.json, src/resources/beta/environments/index.ts

Compact Command and SDK Reference

Use this section as a quick map between command-line habits and the SDK's generated names. CLI users pass flags; SDK users import or access generated resources and pass typed params. For beta messages, src/resources/beta/messages/index.ts exports Batches with BatchCreateParams, BatchRetrieveParams, BatchListParams, BatchDeleteParams, BatchCancelParams, and BatchResultsParams, plus the Messages resource and many beta content types. For managed memory, src/resources/beta/memory-stores/index.ts exports MemoryStores, Memories, and MemoryVersions, with create, retrieve, update, list, delete, archive, redact, and cursor types where applicable. Sources: src/resources/beta/messages/index.ts, src/resources/beta/memory-stores/index.ts

Area	Concrete exported names to look for
Agents	`Agents`, `AgentCreateParams`, `AgentRetrieveParams`, `AgentUpdateParams`, `AgentListParams`, `AgentArchiveParams`
Agent command-like tool inputs	`BetaManagedAgentsAgentToolset20260401BashInput`, `BetaManagedAgentsAgentToolset20260401EditInput`, `BetaManagedAgentsAgentToolset20260401ReadInput`, `BetaManagedAgentsAgentToolset20260401WriteInput`
Environments	`Environments`, `EnvironmentCreateParams`, `EnvironmentRetrieveParams`, `EnvironmentUpdateParams`, `EnvironmentListParams`, `EnvironmentDeleteParams`, `EnvironmentArchiveParams`
Work	`Work`, `WorkAckParams`, `WorkHeartbeatParams`, `WorkPollParams`, `WorkStatsParams`, `WorkStopParams`
Messages and batches	`Messages`, `Batches`, `BatchCreateParams`, `BatchResultsParams`, `BetaMessageBatch`
Memory	`MemoryStores`, `Memories`, `MemoryVersions`, `MemoryVersionRedactParams`

Implementation Details and Migration Signals

The repository source for these surfaces is generated from an OpenAPI specification, as indicated by the headers in the beta index files. That matters because the SDK's public names, parameter types, and response types are meant to reflect the API schema consistently across resources. When a CLI command exposes a flag like --beta, or when a generated SDK method exposes a params object and request options, both are representing the same API contract at different developer interfaces. Prefer relying on documented command names and exported SDK types rather than inferring behavior from ad hoc request construction. Sources: src/resources/beta/index.ts, src/resources/beta/agents/index.ts

Migration metadata is especially useful for teams that maintain both scripts and TypeScript integrations. The migration config names the package as @anthropic-ai/sdk, the client class as Anthropic, and the base client class as BaseAnthropic, then lists method-level changes. For beta.environments.work, the listed operations now take work_id as the path parameter where older forms included environment_id as well. If a CLI wrapper or internal command runner mirrors SDK method signatures, update the wrapper at the same time as SDK usage so operator-facing commands and application code do not diverge. Sources: bin/migration-config.json

Practical Next Steps

When adopting CLI commands, start with the official command examples and capture the returned IDs in your shell environment or job metadata. Then map each command to the closest SDK resource if the workflow later needs stronger typing, pagination helpers, retries, or application-level orchestration. For beta Managed Agents work, read the environment and work resource reference before building workers that acknowledge and heartbeat jobs. For memory or batch workflows, use the generated parameter names as the shared vocabulary between scripts, SDK code, and operational runbooks.

Related pages: beta-namespace-reference, beta-environments-reference, managed-agent-environments, files-resource-reference, request-options-errors-retries

Ask a question...