Build Your First CLI.
When no MCP covers what a service can really do, you build the CLI yourself. Four phases, walked end to end: scrape the API docs, build the tool, write per-method skills, cache the full spec for everything else. The Slack CLI walkthrough ships 306 methods this way.
- A custom CLI for a service you actually use, with full API coverage instead of the slice the vendor's MCP exposes.
- A starter set of skills that teach the agent your common workflows on top of the CLI, plus a method catalog for the long tail.
- A repeatable pattern. Subsequent CLIs go much faster because the architecture is the same. The next one is half the time.
Build a CLI with Claude.
Hand the four-phase walkthrough off to Claude in one paste. Pick a service, then go end to end with confirmation gates between phases.
How this fits in the OS.
Firecrawl access, a service whose API docs are scrapable, and a reference CLI to study (the public N8N or Google Workspace CLI).
Firecrawl, the target service's API docs, Python or Node for the CLI binary, and Infisical or 1Password for credentials.
Full-API control over services the vendor MCP under-serves, multi-account credential routing, and the long-tail method catalog pattern for everything not yet skilled.
Why a CLI, not just an MCP.
MCPs (Claude Desktop calls these connectors) are convenient. You toggle one on and your agent can suddenly reach into Notion, Gmail, Slack. The problem is that the vendor decides which API capabilities to expose. That's never everything the API can do.
Notion's official MCP can read and write pages. It cannot do complex filtered database queries, bulk operations across many pages, or block-level reordering. The full Notion API can do all of those. Your agent hits the MCP wall, and you're stuck. A custom CLI wraps the entire API. The agent uses the CLI for everything. The MCP becomes a safety net you can leave toggled on, or remove entirely.
The Google Workspace CLI at github.com/googleworkspace/cli has 26.5k stars and ships Claude skills alongside the binary. It exists because Google's official MCP doesn't cover enough. Thousands of teams chose this route over the vendor MCP.
Closer to home, the AI Build Lab team ships CLIs for N8N (open source at github.com/8Dvibes/n8n-cli, PyPI: n8n-toolkit), Slack (github.com/8Dvibes/slack-toolkit, PyPI: slack-toolkit, 306 methods + 33 skills, the worked example in this guide), and Zoom. All follow the same four-phase pattern. The architecture on this page isn't novel. It's the standard for production agent fleets.
When to skip building
Building a CLI is real work, roughly a one-day job. Skip it when:
- Someone already shipped it. First move, always. Check the Borrow a Working CLI shelf. The N8N, Slack, Zoom, and Google Workspace CLIs are already built and ship with their own skills. Install one, write your own skills on top, save yourself a day. The one-day build below is for cases where no shipped CLI fits.
- You're prototyping. MCPs are instant, CLI takes a day. Get the MCP working first, then build only if you hit a wall.
- The MCP covers everything you need. Don't over-engineer. The capability gap has to be real, not theoretical.
- The auth flow is painful. Some OAuth implementations are not fun to reimplement. If the MCP handles auth for you and you don't need the extra capability, keep the MCP.
- You don't own (or can't scrape) the docs. Some tools have poor or gated documentation. Without docs, the agent can't build the CLI.
The one structural reason MCPs lose.
Most reasons to build a CLI are about capability coverage. There's one more reason worth surfacing up front, because it has nothing to do with capability and everything to do with structure: multi-account.
MCPs are one-account-at-a-time. Two Google Workspaces, two Slack workspaces, three Notion teams, the MCP can only connect to one at a time. Switching means disconnect, reconnect. No clean way to say "use the personal account for this command, the work account for that one."
CLIs handle credential routing per command. The Google Workspace CLI supports four ways to pick an account:
- Per-project override. A
CLAUDE.mdin each project specifies which account is the default. - Per-recipient domain. A skill checks the recipient domain and picks the matching account.
- Explicit flag.
gws --account=personal gmail send. - Skill-level preset. A workflow skill hardcodes the right account.
Cleanest pattern in practice: skill-level preset for client-facing workflows, plus a CLAUDE.md routing rule for the default. If you run multiple accounts on a tool you use heavily, the CLI is paying down a structural limitation, not adding capability. That's a different motivation than "the MCP can't do X" and an honest one.
The four phases.
Building a CLI from scratch sounds intimidating. In practice it's four phases, and Claude Code does most of the work for you in each one. Each phase produces a layer of the same architecture.
What follows is each phase in order. The starter prompt above walks you through all four with confirmation gates between each one.
Walk through the phases.
Scrape the API docs
~30 minThe agent can't build a CLI it doesn't understand. Phase 1 gives it the full reference. You can use Firecrawl, curl, or any docs scraper. The goal is a local copy of every endpoint, every parameter, every capability, saved as markdown.
Tyler calls this "building your own Context7" because you're localizing the docs the agent depends on, instead of trusting that the model's training data has them current.
In our local repo, use Firecrawl to scrape the full API reference for <service>. Save it to docs/<service>-api/ as one markdown file per method group. Include every method's parameters, required scopes, rate limits, and an example response. We are using these docs as the source of truth when we build the CLI in the next phase.
The agent does this for you. You don't curl 300+ pages by hand. If the tool has fragmented docs (some on a marketing site, some on a developer subdomain, some in OpenAPI specs), the agent pulls from multiple sources and merges them.
Build the tool
~3-4 hoursHand Claude the docs you just scraped, plus a reference CLI to study as the architectural template. The public N8N CLI at github.com/8Dvibes/n8n-cli is the closest in spirit (Python, zero deps, agent-first output, built by the AI Build Lab team). The Google Workspace CLI at github.com/googleworkspace/cli is the gold standard (Rust, 26.5k stars, ships with Claude skills). Either works. Pick one and have Claude read it before writing any code.
Build incrementally. The agent doesn't write 300+ commands in one pass. It builds the core (auth, structured output, a handful of resource commands). You QA it. Then it adds the rest. The CLI is its own test suite.
Read github.com/8Dvibes/n8n-cli as the architectural template (start with the README, then skim the command structure under n8n_cli/commands/). Then read the docs we just scraped for <service>. Come back with: (1) your understanding of what we're building, (2) a gap analysis (what does the vendor's MCP not do that the API can), and (3) a proposed CLI architecture and initial command set. Don't write code yet. Show me the plan first.
What Claude came back with on the Slack CLI build:
- Gap analysis. "Slack's official CLI is purely developer tooling for building Slack apps. It cannot post messages, read channels, search, or manage users. There's no existing CLI that wraps the 306 web API methods for automation use. That's our gap."
- Architecture proposal. Zero-dependency Python CLI wrapping Slack's web API, paired with Claude skills and a searchable method catalog.
- Initial command set. Common operations: post message, list channels, search, manage users. Then the catalog handles everything else.
Once you approve the proposal, the agent builds. You'll watch the first few commands work end to end before letting it finish the rest.
Write per-method skills
~1-2 hoursPhase 2 gave you a CLI that can do everything the API can do. That's the capability layer. Phase 3 is the intelligence layer. You teach the agent when to use which command and how you specifically use it.
Quick definition. A skill is a markdown file Claude Code reads when triggered. Think of it as a written procedure your agent can follow. Skills live in ~/.claude/skills/ (available in every project) or <project>/.claude/skills/ (only that project). When you build one, you describe the workflow in plain English and the agent generates the file.
The CLI gives the agent the capabilities. Skills stack on top, chaining those capabilities into the workflows you actually run. A skill is multi-step by design. The decision test: not "do I have the command?" but "do I have a workflow I'd want to replay without explaining it again?" If yes, that's a skill.
Example: the "after meeting" skill. It isn't one command. It's a workflow that chains five:
- Pull the meeting transcript from the Zoom CLI
- Pull the Zoom chat log
- Generate a summary and action items
- Post the summary to the right channel via the Slack CLI
- Log to an activity feed
That skill knows the right order, the right channel, and your conventions. The CLIs do the actual work. Skills can call other skills, so you build a small library of CLI-bound skills (/slack-post, /zoom-get-transcript) and then build workflow skills on top that orchestrate them. If the Slack CLI changes, you update /slack-post once and every workflow inherits the fix.
Start small. Your first CLI doesn't need 30 skills. Five is fine. The most common operations you actually run. The rest fall through to Layer 3.
The agent does this for you. You describe the workflow in plain English, the agent drafts the skill file (the YAML front matter, the procedure steps, the trigger description). You read the draft, approve it or edit it, save. The agent runs it next time the workflow comes up.
Cache the full spec for everything else
~1 hourSlack has 306 web API methods. Notion has hundreds. You'll never write a skill for every one. Phase 4 solves the long tail.
The pattern, borrowed from Vercel's OpenSRC tool: cache the full API method catalog locally as searchable structured data. When the agent encounters an operation without a skill, it does this:
- Searches the catalog:
slack-cli methods search emoji - Pulls the full schema for a match:
slack-cli methods get emoji.list. Returns parameters, required scopes, rate limits. - Composes the API call dynamically using the real spec. Calls the CLI to execute it.
It doesn't build scaffolding. It gives the agent a library card. The agent hits something it doesn't have a skill for, the CLI method search finds it, gets the full schema (parameters, scopes, rate limits) and composes the call dynamically.
Without Phase 4, every new operation needs a new skill or a manual prompt. With Phase 4, the agent self-serves anything in the API spec. Your CLI grows from "the things you wrote skills for" to "the things the API can do." That's a big difference.
The N8N CLI works this way already. N8N constantly adds and updates nodes. Instead of maintaining static docs for every node, the catalog pulls current node info in real time, only when the agent needs it.
The agent does this for you, too. You don't curate the catalog by hand. Phase 4 is one prompt asking Claude to build the methods subcommand and index the docs you scraped back in Phase 1. The catalog updates whenever you re-run that command against fresher docs.
What this enables at scale.
The pattern compounds. Each new CLI is faster to build because the architecture is established. Each unlocks new workflows. Each workflow becomes a skill, then a meta-skill that proposes more skills. A snapshot of the team's production fleet:
You don't reach those numbers in one cohort. You reach them by shipping one CLI, then another, then another. The first one is the hard one. After that, the pattern carries.
Where the CLI and the skills live.
Two layers, two places. The CLI tool lives on your computer, installed in your OS path. You don't use the CLI directly. The agent does, by calling it through the Bash tool.
The skills that know how to call the CLI live in one of two places, depending on whether the tool is useful in every project or just one:
Why not install everything globally? Tool-selection bloat. Too many globally-available tools dilute the agent's selection accuracy. The agent picks the wrong tool, or doesn't pick a tool when it should. The fix is to project-scope what isn't universal. If a project-scoped skill ends up being copy-pasted into a second project, promote it to global. Don't keep two copies in sync.
What changes for you.
The CLI is the easy part. The bigger thing is the shift in how you think about tool access. Three shifts you'll feel:
- You stop waiting on vendors to expose what you need. The CLI is your interface, not theirs. If the API can do it, your agent can do it.
- You start thinking in workflows. A skill stops being "wrap a command" and becomes "encode the way I actually do this." Skills compose. Workflow skills orchestrate CLI-bound skills, and the multi-step real work moves into the catalog.
- You unlock the structural territory MCPs can't reach. Multi-account. Per-command credential routing. Helper commands tuned to your workflow. The CLI plus skills pattern compounds in ways the MCP single-tool model can't.
This is the moment your agent stops feeling like a chatbot with tools and starts feeling like a co-worker who knows how your stack actually works.
If you get stuck.
Common failure modes, ranked by how often they bite people:
- Picked too ambitious a first CLI. Most common. Start with a tool where you've already hit the MCP wall on one specific thing. Don't pick the most complex API in your stack as your first.
- Skipped the proposal step in Phase 2. Let Claude start writing code without showing you the plan first. Stop the build, say "show me the architecture and command set first." Catch mistakes cheaply.
- Wrote 30 skills in Phase 3. The catalog handles the long tail. Five skills for your most common workflows, then ship. You can always add more.
- Forgot the placeholder pattern. Pasted a real API key into the chat by accident. Rotate the key immediately, then redo the credential step with Infisical or 1Password and the
PASTE_HEREplaceholder pattern. If Claude offers to enter the real key for you, say no. You always type real values directly into your password manager. - Built a CLI for a tool the MCP already covers. Check the MCP's actual gap before building. The capability gap has to be real, not theoretical. Sometimes the right answer is "the MCP is fine, write better skills on top of it."
Still stuck? Post the prompt, the agent's response, and what you expected, in the workshop Slack. Someone in the cohort is solving the same thing.
Where to go next.
You shipped the first CLI. The pattern compounds from here. The natural next moves on the shelf: