Getting started with the Clanker CLI
Install Clanker, configure providers, resolve execution context, ask grounded questions, review plans, share credentials, and expose MCP.
The whole story in 7 lines
Walk through CLI installation, configuration, execution context, a grounded question, maker plans, shared credentials, and talk or MCP.
- Confirm a supported installation path and the resolved binary version before configuring any provider.
- clanker.yaml needs an AI profile, an infrastructure default, and credential references rather than embedded secrets.
- Runtime flags override configuration defaults, so the resolved execution context determines the provider, account, and project.
- The ask command classifies the target surface and runs focused evidence probes instead of querying every provider.
- Generate a JSON plan for review before applying it, with destructive operations held behind an additional confirmation boundary.
- A backend vault enables remote calls, while local configuration is only a fallback when the backend has no matching secret.
- Talk supports interactive terminal sessions, while MCP exposes a bounded tool surface to external clients.
Setup
You installed Clanker because you want one grounded answer about a real system. The risky part is letting a vague command reach the wrong provider, account, or credentials. We will keep each boundary visible so the first useful query is also a configuration audit.
Four terms keep the path clear. The CLI is the local program, a provider owns external data, execution context chooses concrete access, and MCP exposes a deliberate tool surface to another client. Those roles must not blur together.
The route crosses seven boundaries from installation to an external client. Each boundary either establishes state, proves that configuration works, or narrows what the next command may do. A failure therefore has a specific layer to inspect.
We will follow one setup from a missing binary to a verified tool surface, with credentials kept outside the commands themselves. Let us begin by installing the CLI and checking the exact version the shell resolves.
Install the CLI
★ If you remember one thing · Source installation and Homebrew take different routes, but both must end with one verified local Clanker binary.
Start by choosing how to install the binary. Homebrew works, but `make install` usually tracks the freshest source. We keep this boundary explicit because later commands depend on the state created here. This detail matters because it determines the state handed to the next part of the system.
The stage has reached the decision that determines its next state. Which command proves the installed Clanker binary is reachable on PATH?
Clanker can only query real cloud surfaces if the matching provider CLIs, such as AWS CLI v2, are already available. The key lesson is where Clanker gets this information and when a command may override it.
Switch the Install control through every choice. Compare the downstream outcome while the earlier input and system boundary remain fixed.
Once this passes, you have a working entrypoint for the rest of the workflow: `ask`, `config`, `credentials`, `talk`, and `mcp`. With this piece in place, the next stage can build on a known execution context.
Bootstrap ~/.clanker.yaml
The next job is to give Clanker a baseline configuration instead of forcing every run to start from zero. We keep this boundary explicit because later commands depend on the state created here. This detail matters because it determines the state handed to the next part of the system.
You can generate that baseline with `clanker config init` or copy the example file into `~/.clanker.yaml`. That separation makes failures easier to diagnose before a live provider receives any work.
The stage has reached the decision that determines its next state. Which file supplies Clanker defaults before command flags override them?
Then wire in the provider key and the default infra environment so runs have a home context. Debug output can trace the same decision when a command behaves differently than expected.
Think of `~/.clanker.yaml` as the starting state. Later flags can override it, but every run begins here. With this piece in place, the next stage can build on a known execution context.
Resolve Execution Context
When you run `clanker ask`, the config file is only the starting point, not the final truth. We keep this boundary explicit because later commands depend on the state created here.
Clanker first loads the defaults it can find from config and environment variables. This boundary matters because every later step depends on the state established here. That separation makes failures easier to diagnose before a live provider receives any work.
Then runtime flags like `--aws`, `--profile`, or `--ai-profile` override that baseline for this specific command. The key lesson is where Clanker gets this information and when a command may override it.
The command does not proceed until provider, credentials source, model, and backend endpoint are all resolved. Debug output can trace the same decision when a command behaves differently than expected.
Only after that context is pinned down does the question move into routing and evidence collection. With this piece in place, the next stage can build on a known execution context.
Run the First ask
Your first useful run should be one concrete natural-language question, not a pile of hand-written provider commands. We keep this boundary explicit because later commands depend on the state created here.
Clanker reads the question and classifies which surface it belongs to before touching any live clients. That separation makes failures easier to diagnose before a live provider receives any work.
That routing step matters because only the matching probes run. Unrelated AWS, GitHub, or K8s calls stay out of the path. The key lesson is where Clanker gets this information and when a command may override it.
The returned fragments are compacted into grounded evidence rather than dumped raw into the terminal. Debug output can trace the same decision when a command behaves differently than expected.
What you finally see is a typed answer, or route JSON if you asked for `--route-only`. With this piece in place, the next stage can build on a known execution context.
Turn Prompts into Plans
Read-only answers are the default, but Clanker can also turn a prompt into an execution plan. We keep this boundary explicit because later commands depend on the state created here.
Adding `--maker` changes the first output from prose into structured plan JSON for the target provider. That separation makes failures easier to diagnose before a live provider receives any work.
That plan is meant to be reviewed, because the safe workflow is prompt, then plan, then approval. The key lesson is where Clanker gets this information and when a command may override it.
Only after review do you feed the plan back through `--apply`, either from stdin or a saved plan file. Debug output can trace the same decision when a command behaves differently than expected.
If the request is destructive, Clanker keeps it behind `--destroyer` plus explicit confirmation. This boundary matters because every later step depends on the state established here. With this piece in place, the next stage can build on a known execution context.
Share Credentials Across Machines
Now consider the cross-machine case, where the current laptop does not have the provider profile you need. We keep this boundary explicit because later commands depend on the state created here.
The `credentials store` flow uploads a provider credential set from the local machine into the backend vault. That separation makes failures easier to diagnose before a live provider receives any work.
That vault ties the secret to your Clanker API key so a different machine can request the same provider context. The key lesson is where Clanker gets this information and when a command may override it.
A remote `clanker ask --api-key ...` run checks the backend first, then falls back locally if the secret is missing. Debug output can trace the same decision when a command behaves differently than expected.
Either way, the stage ends with a hydrated provider client that can gather real evidence for the answer. With this piece in place, the next stage can build on a known execution context.
Use talk or MCP
Once the core CLI works, you can expose the same engine through either a chat loop or an MCP server. We keep this boundary explicit because later commands depend on the state created here.
Use `clanker talk` when you want an interactive terminal conversation instead of one-shot commands. That separation makes failures easier to diagnose before a live provider receives any work.
Use `clanker mcp` when another client needs tool access over HTTP or stdio. This boundary matters because every later step depends on the state established here. The key lesson is where Clanker gets this information and when a command may override it.
That MCP surface publishes a small toolset, including version lookup, route selection, and command execution. Debug output can trace the same decision when a command behaves differently than expected.
At that point, Clanker is no longer just a CLI. It can sit inside a terminal chat, another agent, or a larger toolchain. With this piece in place, the next stage can build on a known execution context.
Recap
We can now connect Install the CLI to the workflow. Homebrew exists, but source install plus the right provider CLIs is the safest path when you actually plan to query live infra. This callback keeps the final operating path grounded in a concrete boundary.
We can now connect Bootstrap ~/.clanker.yaml to the workflow. You only need a small baseline: an AI profile, an infra default, and the env vars or config keys that satisfy that profile. This callback keeps the final operating path grounded in a concrete boundary.
We can now connect Resolve Execution Context to the workflow. Config defaults are only the starting point. Runtime flags like `--profile`, `--ai-profile`, and provider selectors win when they are present. This callback keeps the final operating path grounded in a concrete boundary.
We can now connect Run the First ask to the workflow. Clanker does not shotgun every backend. It classifies the surface first, then runs only the evidence probes that matter for that question. This callback keeps the final operating path grounded in a concrete boundary.
We can now connect Turn Prompts into Plans to the workflow. The safe path is prompt -> JSON plan -> human review -> `--apply`. Destructive requests stay behind `--destroyer` and explicit confirmation. This callback keeps the final operating path grounded in a concrete boundary.
We can now connect Share Credentials Across Machines to the workflow. The path is local credential export -> backend vault -> remote ask with `--api-key`, but Clanker still falls back to local config when the backend. This callback keeps the final operating path grounded in a concrete boundary.
We can now connect Use talk or MCP to the workflow. `clanker talk` is for interactive terminal conversations. `clanker mcp` is for external clients that want `clanker_version`. This callback keeps the final operating path grounded in a concrete boundary.
The complete path begins with a verified binary, resolves configuration and authority, gathers evidence, gates changes through plans, and exposes deliberate client surfaces. That is the workflow to carry forward.
The whole story in 7 lines
Walk through CLI installation, configuration, execution context, a grounded question, maker plans, shared credentials, and talk or MCP.
- Confirm a supported installation path and the resolved binary version before configuring any provider.
- clanker.yaml needs an AI profile, an infrastructure default, and credential references rather than embedded secrets.
- Runtime flags override configuration defaults, so the resolved execution context determines the provider, account, and project.
- The ask command classifies the target surface and runs focused evidence probes instead of querying every provider.
- Generate a JSON plan for review before applying it, with destructive operations held behind an additional confirmation boundary.
- A backend vault enables remote calls, while local configuration is only a fallback when the backend has no matching secret.
- Talk supports interactive terminal sessions, while MCP exposes a bounded tool surface to external clients.