Clay Moved to the Terminal: What the Clay CLI Means for GTM Teams

Clay spent five years being a spreadsheet you click. Then it shipped a command-line interface, and the interesting part is not the feature, it is what the feature admits: the buyers who get the most out of Clay are no longer marketers building a table, they are operators building a pipeline that has to run on a schedule, in a repo, next to everything else. We installed the CLI in July 2026, ran it against a live workspace, hit the parts that are gated, and rebuilt what we could not reach. This is the operator's read: what the Clay CLI is, what it actually does today, where it stops, and whether moving your Clay work to the terminal is worth it for your team.

What is the Clay CLI?

The Clay CLI is a command-line client for Clay that lets you drive your workspace from a terminal or a script instead of the web app. It authenticates over OAuth with clay login, storing a session locally, and it exposes your workspace through subcommands: search against Clay's native company and people dataset, plus routines, tables, workflows, webhooks, functions, workbooks, users, credits, and api-keys. The design choice that matters most is that it is JSON-first: successful commands print JSON to stdout and exit zero, and failures print a structured {error: {code, message}} to stderr with a non-zero exit code. That contract is what makes it composable. You can pipe it into jq, wrap it in a Python script, call it from an n8n or cron job, or hand it to a coding agent and have the agent read the errors and correct itself. It is distributed through Clay's agent-plugin bundle rather than public npm, so installation is the least standard part of it.

What can you actually do with the Clay CLI today?

Today the CLI is strongest at discovery, workspace introspection, and automation plumbing, and weakest at reading the tables you already built. In our workspace we could authenticate and confirm identity with clay whoami, read live credit balance with clay credits, list real workbooks, and enumerate routines, functions, workflows, and webhooks. clay search queries Clay's own company and people dataset from the terminal, which means list-building becomes a scriptable step rather than a session in a browser tab. You can also mint public API keys with clay api-keys create, scoped to a single workspace, for use in your own scripts. The practical pattern that emerges: use the CLI as the control plane for the parts of Clay that generate and orchestrate work, and keep the web app for building and debugging column logic visually. Anything you would previously have done by opening a workbook and clicking run, you can now trigger from the same place your other jobs run.

What can the Clay CLI not do yet?

The honest answer is the one that changes your architecture: you cannot reliably read your own workbook rows. In our workspaces, clay tables list, rows, and query return auth_forbidden with a message that the public observability API is not enabled, which is an Enterprise plan gate rather than a bug or a version problem. We hit the same wall in two separate workspaces. Clay's public REST API is also still a stub at the time of writing: the clay-api-key header authenticates fine, but only GET /me is live while /tables, /credits, and /sources return 404, so credits and workbooks are readable through the CLI's authenticated proxy and not through raw REST. The MCP server has the mirror-image limitation: it can search companies and contacts and run enrichment, but it cannot read a curated workbook table either. If your plan is "we will read our Clay tables programmatically and sync them out," verify that on your plan before you design around it.

Why does a CLI matter more than it sounds like it should?

Because a CLI is how a tool stops being a destination and becomes a component. A web app forces a human to be present at the moment work happens. A command-line interface with a JSON contract can be called by a scheduler, a workflow engine, or an agent, which means the work happens whether or not anyone opens a tab. That is the entire difference between a GTM tool and GTM infrastructure. It also changes who can operate it: once every step is a command, your pipeline becomes text, and text can be versioned, reviewed, diffed, and rerun. Most teams treat their enrichment logic as tribal knowledge living inside one person's workbook. A scripted pipeline is documentation that executes. This is why we run our entire motion from a terminal rather than from six dashboards, described in running your entire GTM motion from one place, and why the CLI is a bigger signal about Clay's direction than any individual feature release.

Should your team move its Clay work to the terminal?

Move to the terminal when your Clay work is repetitive and scheduled, and stay in the web app when it is exploratory. The split is clean in practice. Building a new enrichment chain, debugging why a provider returns nulls, or designing a scoring column is faster visually, because you want to see the cell. Running the same sourcing sweep every Monday, refreshing a signal table on a cadence, or triggering enrichment as one step inside a larger pipeline is faster and more reliable as a command, because it removes the human from the loop and leaves a log. The real prerequisite is not skill, it is repetition: if a workflow has run more than five times by hand, it should be a script. Teams without that repetition will get nothing from the CLI except a new install to maintain. Teams with it usually find that the terminal is not the upgrade, the scheduling and the audit trail are.

What do you do about the parts Clay does not expose?

You either wait for the plan gate to lift, export CSVs by hand, or build the missing layer yourself. We chose the third option. Because table reads and enrichment reads were gated on our plan, we built a small internal CLI of our own, techtower-clay, that creates and reads data tables locally against our own provider keys, so building and enriching a list costs provider spend rather than per-action credits. It stores every enrichment column with a reproducible recipe, the exact prompt, model, endpoint, or template used, so any column can be rerun months later without anyone remembering how it was built. It runs as both a CLI and an MCP server, so the same 23 operations are available to a human at a prompt and to an agent in a loop. That is not a recommendation to rebuild Clay. It is the general principle: when a vendor gates the read layer, own the read layer, and keep the vendor for what it is genuinely best at.

How does this change the buy-versus-build question?

It narrows the gap, in both directions. Clay's advantage was never only its data, it was that the waterfall, provider fallbacks, and credit accounting were already solved and visible. A CLI extends that advantage into scripted pipelines, so the thing you would have built in code now has a supported command. At the same time, once your GTM logic lives in scripts, swapping a component becomes a code change rather than a migration, which quietly lowers the cost of building the parts you actually need. The decision therefore stops being "Clay or build" and becomes "which layer do we own." Our answer across 30-plus projects: buy the enrichment waterfall, own the orchestration, and never let a vendor hold the only copy of your logic. We break the economics down in Clay versus building your own enrichment waterfall.

One installation detail that will cost you an afternoon

The CLI is distributed as a pinned bundle, not through public npm, and the pin can go stale in a way the tool will not fix for you. Our install ran fine on 0.1.14 until Clay's servers began rejecting that version with a message to upgrade to 0.1.17 or higher. The obvious move, clay update, is a no-op, because the version is managed by the plugin bundle rather than by the CLI itself. The actual fix is to bump the pin: the launcher downloads a platform binary for the version recorded in the bundle's cli-version file and checksum-verifies it against the bundled checksums.txt, so you update both files from the matching release and rerun the command, which re-downloads and caches the new binary. Back up both files first. It takes ten minutes once you know, and an afternoon if you assume a version flag or an update command will handle it.

The takeaway

The Clay CLI turns Clay from a place you visit into a component you call, which is a meaningful upgrade if your outbound already runs on a schedule and close to irrelevant if it does not. Today it is genuinely good at search, workspace introspection, credits, and automation plumbing, and it is blocked at reading your own workbook rows unless you are on a plan with the observability API enabled. The public REST API is still a stub. Plan around both before you rewrite anything. Most teams read a CLI release as a new tool to learn. Read it instead as the vendor telling you where the leverage moved: from clicking through a table to operating a pipeline. If you want the wider frame for that shift, start with what GTM engineering is.