Build your first agent with the CLI

With the caplo CLI you keep agents and tool packages as files in your own repository and publish them from your terminal or CI. This quickstart scaffolds the summit example: an outdoor gear shop with a concierge agent that routes customers to three specialist agents, plus two tool packages with mock data.

Before you start

• A Caplo account. If you have never signed in, sign in once at app.caplo.si; Caplo creates a workspace for you.
• The Owner or Admin role in the workspace. The project pushes tool packages and agents and publishes both, which no other role can do alone. See Workspaces and roles.
• Node.js 24 and npm, to install the tool packages’ dependencies.
• Fast decisions turned on for the workspace. The summit concierge uses fast routing to pick a specialist, and an agent with fast routing cannot publish without it. An Owner or Admin turns it on in the console under Settings > AI providers > Fast decisions. See Fast decisions.

Note

If you only want a single agent without tools or fast routing, run caplo init my-assistant instead. It uses the blank template: one agent file and one eval case. The rest of the steps are the same, without the tool dependencies.

Create and publish the project

1. Install the CLI. On macOS or Linux:

   brew install getcaplo/tap/caplo

   Or install it to ~/.local/bin without Homebrew:

   curl -fsSL https://cli.caplo.si/install.sh | sh

   See Install the CLI for Windows, version pinning and verifying signatures.

2. Sign in.

   caplo auth login

   Your browser opens to sign in; on a machine without a browser, use caplo auth login --device. If you belong to one workspace, the CLI selects it. Otherwise pick one:

   caplo workspace list
   caplo workspace use "<WORKSPACE_NAME>"

   caplo auth status shows who you are signed in as and which workspace commands act on.

3. Scaffold the project.

   caplo init shop --template summit
   cd shop

   The project name comes from the directory and becomes part of each agent’s name. You get:

   Path	Contents
   caplo.yaml	The project file. It finds agents in agents/*.yaml and tool packages in tools/*.
   agents/concierge.yaml	Shop Concierge, the entry agent. It routes to the three specialists with fast routing.
   agents/orders.yaml	Shop Orders: looks up orders and shipments and starts returns.
   agents/gear.yaml	Shop Gear: recommends products and checks store stock.
   agents/returns.yaml	Shop Returns: answers return and warranty policy questions from its instructions.
   tools/order-desk/	An MCP server package with mock data: lookup_order, track_shipment, search_products and check_return_eligibility (reads) and create_return (a write that the customer must confirm).
   tools/store-stock/	A function package with one read tool, check_store_stock.

   Every agent file includes eval cases. The agents use an Anthropic model; if your workspace cannot use it, change model.name in each agent file. See Instructions and model.

4. Install the tool dependencies. Each package needs its dependencies and a lockfile before Caplo can build it.

   (cd tools/order-desk && npm install)
   (cd tools/store-stock && npm install)

5. Validate the project. This runs offline and checks the files against the schemas, every tool and sub-agent reference, and the sub-agent links.

   caplo validate

   You can also run the tool packages’ test fixtures locally with caplo test.

6. Push the drafts.

   caplo push

   The CLI uploads and builds both tool packages, then saves each agent as a draft, specialists before the concierge. Nothing is published yet and no customer can reach the agents. Agents and packages are matched by name, so pushing again updates them.

7. Chat with the draft.

   caplo agent chat "Shop Concierge"

   Type one message per line, for example Where is my order SO-1002? or Can you recommend a lightweight two-person tent? Each reply shows the sub-agents and tools the turn used. When the agent proposes a write such as create_return, the CLI shows what it will do; type /confirm to approve it or /cancel to decline. Ordinary text never approves a write. End the chat with /exit or Ctrl-D.

   This is a private test conversation, but tools run for real. The summit tools only use mock data.

8. Preview the publish.

   caplo publish --dry-run

   The plan lists what will be published, in order: the tool packages, then the specialists, then the concierge, pinned to the specialists’ new releases.

9. Publish. A project’s first publish to a workspace needs --yes, after you have reviewed the plan:

   caplo publish --yes

   For each agent the CLI pins the exact tool versions, runs its eval cases, and creates a release. Every eval case must pass unless your workspace has made evals advisory. If a case fails, the CLI prints why and stops with exit code 3; fix the agent file or the case and run caplo publish again. Later publishes show the plan and ask before going ahead.

Your agents now have releases in the workspace, and you can see them under Agents in the console.

Put it on your website

Channels are created in the console. Follow Add an agent to your website and choose Shop Concierge as the channel’s agent. After that, publish new releases with caplo publish and move the channel to them with caplo channel deploy; see Agents and releases.

Let an AI assistant do it

AI prompt

Scaffold and publish a Caplo agent project with the CLI

Creates a Caplo project from the summit template, pushes and tests it, then publishes it after asking you.

Copy promptOpen in ClaudeOpen in ChatGPT

Show prompt

Goal: create a Caplo project in this repository with the `caplo` CLI, push it to my workspace as drafts, test it in a chat, and publish it only after I approve.

Read these pages first:
- https://docs.caplo.si/get-started/quickstart-cli.md
- https://docs.caplo.si/cli/projects.md
- https://docs.caplo.si/concepts/agents-and-releases.md
- https://docs.caplo.si/concepts/evaluations.md

Inputs:
- Project directory and name: <PROJECT_NAME> (lowercase letters, digits and hyphens, starting with a letter)
- Template: <TEMPLATE> (summit for the multi-agent example with tools, or blank for one agent)
- Workspace: <WORKSPACE_NAME>

Steps:
1. Check the CLI is installed with `caplo version`. If it is missing, tell me to install it (`brew install getcaplo/tap/caplo`) and stop.
2. Run `caplo auth status`. If I am not signed in, ask me to run `caplo auth login` myself, then continue.
3. Run `caplo workspace use "<WORKSPACE_NAME>"`.
4. Run `caplo init <PROJECT_NAME> --template <TEMPLATE>`, then work inside `<PROJECT_NAME>`.
5. If the template is summit, run `npm install` in `tools/order-desk` and in `tools/store-stock`. Keep the generated `package-lock.json` files.
6. Run `caplo validate` and fix any problem it reports in the files you created.
7. If the template is summit, run `caplo test` and report the fixture results.
8. Run `caplo push`. Report each tool package and agent it created or updated.
9. Chat with the entry agent: run `caplo agent chat "<ENTRY_AGENT_NAME>"` (for summit, the entry agent is the project title followed by Concierge, for example "Shop Concierge" for a project named shop; for blank, the title followed by Assistant). Send two or three realistic customer messages, one per line, then `/exit`. If the agent proposes a write, answer `/cancel`; never `/confirm` without asking me.
10. Run `caplo publish --dry-run` and show me the plan.
11. Ask me whether to publish. Only after I say yes, run `caplo publish --yes`.
12. If publishing stops on a failed eval case (exit code 3), show me the case and the grader's reason, propose a fix to the agent file or the case, and wait for my approval before changing anything or publishing again.

Verify:
- `caplo validate` passes.
- `caplo agent list` shows the project's agents, each with a release after publishing.

Rules:
- Never paste, print or commit secrets, tokens or API keys. Tool package secrets are set with `caplo secret set` and bound with `caplo tool secret bind`, never written into code or this chat.
- Never publish, revoke releases or deploy channels without asking me first.
- If publishing fails because Fast decisions are disabled for the workspace, tell me: an Owner or Admin must enable it in the console under Settings, AI providers. Do not remove fast routing to work around it unless I ask.
- Do not edit files outside the project directory.

Next steps

• How projects, selectors and environments work: Projects and Environments.
• The day-to-day loop of editing, pushing and publishing: CLI workflow.
• Every field of an agent file: Agent YAML and the agent YAML reference.
• Writing your own tool package: Write your first tool.
• Commands used here: caplo init, caplo push, caplo publish, caplo agent chat.