Claude Code CLI vs. Claude Agent SDK: Which One Should You Build On?

If you want Claude to help with code, choose based on where the agent will run and who will control it. The Claude Code CLI is a terminal tool that a developer or script runs. The Claude Agent SDK lets application code configure and use Claude Code’s agent features. An agent loop is the cycle in which Claude responds, uses tools, and continues until it finishes a task.

Choose the CLI for terminal work or a simple script. Choose the SDK when you want an agent to work inside a product or service and your code needs to control its tools, events, or sessions. The SDK provides the agent loop and tool execution, but you still operate the process that runs the agent.

The CLI and SDK work at different levels

The CLI gives a developer a ready-to-use way to work with Claude Code in a terminal. It supports interactive coding and non-interactive runs: a script can pass a prompt, then receive text, JSON, or streaming JSON output. The CLI reference also documents options for working directories, permissions, tools, and sessions.

With the SDK, your code configures and uses agent interactions. Anthropic says the SDK runs the agent loop and tools inside a process you operate. With a lower-level API client, your code manages each request and response itself. The Anthropic overview of build options places the SDK between a direct API integration and a hosted agent runtime.

Use the CLI for terminal work and simple automation

The CLI fits coding work that happens in a repository and stays close to the developer’s terminal. A developer can use it directly, or a script can run it in print mode with -p. For example, a CI job that sends a prompt and consumes a JSON result can use the CLI without adding an SDK integration.

When a shell command can pass the input and interpret the output, the CLI offers a direct, simple option. The CLI also supports session continuation and resumption, so each terminal interaction does not have to start a separate session.

The CLI is less convenient when your code needs to respond to events during a run, show agent sessions to users, or provide tools specific to your product. A shell command gives your code less control over these interactions.

Use the SDK when application code needs control

Use the SDK when an agent needs to work inside a product, service, or internal tool. Your code can configure the interaction, handle messages as they arrive, and connect the agent’s actions to your product’s interface or logic.

Anthropic’s cookbook distinguishes a one-off query() interaction from a persistent ClaudeSDKClient, which supports follow-up interactions and session state. The examples also show custom tools and hooks. A hook is application-supplied logic that runs at a defined point in an interaction, such as when the agent receives a prompt or attempts a tool call. These patterns are useful when the application must check or shape what happens during an agent run, rather than only consume a final answer. See the SDK integration examples.

With the SDK, you are responsible for operating the agent process. Your service must start the process, route each request to the process for its session, respond to crashes, and store conversation transcripts. Anthropic’s agent hosting guidance covers these deployment tasks. Before choosing the SDK, decide who will operate the agent process and how your service will preserve or resume sessions.

Check permissions, settings, and authentication

Both options require deliberate permission choices. The CLI exposes controls for allowing or denying tools and selecting a permission mode. The SDK lets application code configure behavior, but that control does not make tool access safe by itself. Decide which tools the agent needs and set permissions to match the work it should perform.

Also check how the SDK version you install loads prompts and local settings. The Python SDK’s 0.1.0 release included breaking changes to defaults, including changes to loading the Claude Code system prompt and filesystem settings such as CLAUDE.md. Later cookbook examples discuss settings behavior for 0.2. Those release-specific details are a reason to read the migration notes for your installed version rather than assume an SDK run will match a developer’s CLI session. The Python SDK changelog records the changes.

If you build a product with the Agent SDK, authentication also affects the design. Anthropic’s legal and compliance guidance says product developers should use API-key authentication through Claude Console or a supported cloud provider. It says Claude subscription OAuth is for ordinary use of Anthropic applications and does not allow third-party developers to route their users’ requests through subscription credentials.

Don’t choose by assumed speed or price

The available evidence compares how you integrate each option and what you must operate. It does not show that the CLI or SDK is faster, cheaper, or better at the same task. Pricing depends on the account and provider arrangements.

For a simple script, start with the CLI’s print mode. Move to the SDK when your code needs to control the interaction. For a product feature that needs live events, custom tools, or multi-turn sessions, start with the SDK and plan to operate the agent process and manage its sessions. If you want Anthropic to host the agent runtime, consider Managed Agents. Managed Agents is separate from the CLI and SDK, which do not host the runtime for you.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com