[
    {
        "role": "user",
        "content": "how%20does%20using%20claude%20sdk%20differ%20from%20calling%20the%20local%20claude%20code%20cli%3F"
    },
    {
        "role": "assistant",
        "content": "Here\u2019s a detailed comparison between using the **Claude Code SDK** (either via the SDK packages in Python/TypeScript or via CLI headless mode) versus invoking Claude via the **local CLI (`claude` command)**. They overlap heavily, but there are important differences in usage, flexibility, environment, and control.\n\n---\n\n## What they both offer\n\nThese are shared features:\n\n- Both the SDK and the CLI run on top of the same agent framework (\u201cClaude Code\u201d) with the same core capabilities: tool access (file operations, shell, edit, etc.), session management, permission modes, etc. ([docs.claude.com](https://docs.claude.com/es/docs/claude-code/sdk?utm_source=openai))  \n- You can run non-interactive queries (via `--print` or `-p`) in both SDK (when invoked from command-line) and CLI. ([code.claude.com](https://code.claude.com/docs/en/headless?utm_source=openai))  \n- Support for configuration via `CLAUDE.md`, `.claude/` directory, user/project/local settings. ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/claude-code-features?utm_source=openai))  \n\n---\n\n## Key differences\n\nBelow are the main differences between using the SDK vs using the local CLI directly.\n\n| Aspect | SDK (Programmatic) | Local CLI |\n|---|---|---|\n| **Invocation style** | Via library APIs in Python or TypeScript, or via \u201cheadless\u201d mode using `claude -p \u2026` in scripts. ([code.claude.com](https://code.claude.com/docs/en/headless?utm_source=openai)) | Entering commands manually in terminal, interactive or non-interactive (`claude -p`). ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/cli-reference?utm_source=openai)) |\n| **Integration & embedding** | Closely embedded in programs. You get structured outputs (native message objects), error handling, ability to create callbacks, use custom tools/hook functions in code. You control flows as part of application logic. ([code.claude.com](https://code.claude.com/docs/en/headless?utm_source=openai)) | Mostly terminal-driven. You configure behavior via command-line flags, settings files, environment. Less fine-grained embedding of custom logic inside an app (unless wrapping CLI invocations). |\n| **Control over settings** | SDK gives you `settingSources` options to control which configuration layers to load (user, project, local). You can disable filesystem-based config by setting `settingSources: []`, etc. ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/claude-code-features?utm_source=openai)) | CLI always sees the combination of configuration files by default: your user settings (`~/.claude/`), project settings (`./.claude/`), local/gitignored settings, etc. You can override via flags, but you have less dynamic programmatic control. ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/claude-code-features?utm_source=openai)) |\n| **Use in automation / CI** | SDK is designed for being used in production code, CI/CD pipelines, scripts. Structured output makes it easier to write testable, monitorable agents. ([anthropic.mintlify.app](https://anthropic.mintlify.app/en/docs/claude-code/sdk?utm_source=openai)) | CLI can be used in scripts (via `claude -p`) but tends to be more manual. Parsing output might require more effort (text vs JSON) unless using features like `--output-format`. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/cli-reference?utm_source=openai)) |\n| **Tooling & callbacks** | SDK allows customizing tools or hook functions (post-tool use, permission approval callbacks, etc.) in code. You can assemble agents programmatically with logic branching, etc. ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/claude-code-features?utm_source=openai)) | CLI supports standard tools and permission-modes but doesn\u2019t allow arbitrary code hooks; it\u2019s more about flags and config. CLI has subagents, allowed/disallowed tools, etc., but customization is less dynamic. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/cli-usage?utm_source=openai)) |\n| **Startup & performance** | SDK may incur additional startup cost if it scans filesystem for configuration, skills, etc. You can use flags like `--bare` to speed things up by skipping file discovery. ([support.claude.com](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips?utm_source=openai)) | CLI similarly scans configuration on each run; non-interactive CLI sessions can also use `--bare` to reduce overhead. However, interactive CLI sessions might further persist state in memory (session history). ([support.claude.com](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips?utm_source=openai)) |\n| **Suitability** | Better when embedding Claude agents into larger software, services, automation; when you need structured outputs, programmatic control. | Better for terminal workflows, ad hoc explorations, debugging, local repo work, rapid prototyping. |\n\n---\n\n## When you'd prefer the SDK\n\nYou might opt for the SDK in scenarios like:\n\n- Building a backend service that reacts to events (e.g. GitHub webhook \u2192 run agent \u2192 produce PR).  \n- Embedding agents inside web apps or bots, where control of tool invocation, error handling, and orchestration matters.  \n- CI pipelines, automated quality checks on code, scheduled tasks.  \n- Want fine-grained control over which configs load, dynamic permission modes, hooking into tool usage.\n\n---\n\n## When the CLI is enough / preferable\n\nOn the other hand, the CLI is often fine:\n\n- For prototyping: exploring a codebase, debugging or code review via terminal.  \n- For personal workflows: from the terminal, interactive exploration is natural.  \n- Short tasks where spawning a full application with the SDK is overkill.  \n- Using existing flag-based configuration like specifying allowed tools, mounting directories, etc., without embedding.  \n\n---\n\n## Nuances & gotchas\n\n- Using `settingSources: []` in SDK disables user/project/local settings, but does **not** disable global config files like `~/.claude.json` (global config) or \u201cmanaged policy settings.\u201d ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/claude-code-features?utm_source=openai))  \n- Even when using the CLI, configuration files (project/user/local) and skills/hooks from filesystem contribute to behavior. This can cause surprises when your environment carries configuration you didn\u2019t expect. SDK lets you turn off some of that; CLI less so. ([support.claude.com](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips?utm_source=openai))  \n- The `--bare` flag is useful to reduce startup latency by skipping filesystem scanning, both in CLI and programmatic cases. Without it, context loading (skills, hooks, settings) can slow things. ([support.claude.com](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips?utm_source=openai))  \n\n---\n\n## Summary\n\nUsing the SDK largely gives you:\n\n- Programmatic control  \n- Structured outputs and callback-hooks  \n- Better embedding in automation / services  \n\nWhile the local CLI gives:\n\n- Ease of use from terminal  \n- Quick interactive workflows  \n- Flag-based configuration but less embedded custom logic  \n\nDepending on what you need (automation and integration vs ad hoc use), one may be more appropriate. If you tell me your use-case (scripting vs integration vs personal tooling), I can help you choose which fits better."
    }
]