CLI: Getting started

The Kernel CLI is a command-line tool for importing accounts, running enrichment agents, and exporting data. It is designed to be driven by an AI coding agent, but works equally well when driven by hand.

This guide is split into two parts:

• For humans — a plain-English explanation of what the CLI is, how it works, and what you can do with it.

• For agents — the technical setup for pointing Claude Code at the CLI.

The fastest path: paste this into Claude Code

If you use Claude Code, this prompt is the whole setup. Claude installs the CLI, prompts you to log in, and reads the documentation and skills it needs to drive Kernel correctly.

Set yourself up to use the Kernel CLI.

1. If the CLI is not already installed, install it from
   `curl -sSL https://app.kernel.ai/cli/install.sh | bash`
2. Confirm I'm authenticated by running `kernel --help` and checking
   the user and organization in the header. If not, prompt me to run
   `kernel login`.
3. Read ~/.kernel/AGENTS.md — this is the full usage guide, including
   the live list of agents available on my account.
4. Read the skills under ~/.kernel/skills/ so you know the contracts
   for import, search, enrichment, and Salesforce→Kernel flows.
5. Read the public documentation at
   https://docs.kernel.ai/developer/cli-getting-started for additional
   context.

Once you have done all of that, confirm you are ready and I will tell
you what I want to do.

You only need to do this once. After that, just describe what you want in natural language. If you prefer to install and run commands by hand, the sections below cover the same ground manually.

Install

Run the installer on macOS or Linux:

curl -sSL https://app.kernel.ai/cli/install.sh | bash

The installer places the kernel binary at ~/.kernel/bin/kernel and adds it to your PATH. If Node.js is not already installed, the installer will provision a self-contained runtime so no additional setup is required.

Verify the install:

kernel --help

Log in

Authenticate once per machine:

kernel login

This opens a browser window to complete sign-in. The CLI will remember your session, and your organization is set automatically from your Kernel account.

---

For humans

This section is the mental model of the CLI: what it does, how it is structured, and what it costs. If you understand this section, you understand Kernel.

The four primitives

Every workflow in the CLI is a combination of four primitives:

• Import — a list of accounts you bring in, usually from a CSV. Every import has an ID, and that ID is how you target the accounts in later steps.

• Run — a dispatch of one agent against a list of accounts. This is where the work happens: resolving identity, pulling signals, enriching records. Runs consume credits, because real processing is taking place behind each dispatch.

• Set — a reusable, named population of accounts defined by a filter. Sets are useful once you are past one-off lists and want to work with the same group of accounts repeatedly (for example, "every account in our ICP with more than 500 employees").

• Export — pulls the latest data on a population out of Kernel. Exports are unlimited and free. You can export the same population as many times as you like and always receive the freshest data we hold on those accounts. If you only need a refreshed file, export — do not re-run.

The credit model matters: runs cost, exports do not. That single distinction shapes how customers use the CLI day to day.

The agents

Agents are the specialists that do the actual enrichment and cleaning work. Each one has a narrow focus: one resolves identity, one enriches headcount, one cleans records against your CRM, and so on.

Every Kernel account ships with a core set of agents by default. Beyond that, most customers have custom agents built alongside their data setup: tiering logic specific to their ICP, classifiers for product fit, bespoke CRM cleaning rules, and so on. Custom agents are defined during implementation and show up automatically on your account.

To see the agents actually available to you, run kernel --help or read ~/.kernel/AGENTS.md on your machine.

Default agents (available on every account):

Agent	What it does
identity	Resolves a KERN ID for each account
core-research	Identity plus entity graph. Run this first
headcount	Enriches employee count
revenue	Enriches revenue
location	Enriches HQ and location

Custom agents (vary by account):

Things like full-enrichment, cleaning, tiering, ICP classification, and any workflow specific to your data model. Configured during implementation. If you are not sure what you have access to, check with your Kernel representative or read the local AGENTS.md.

Agent ordering

core-research populates identity and the links into our entity graph. Most specialist agents build on the fields it writes. If you dispatch headcount or revenue against a freshly imported list without core-research first, the run will complete, but results will be sparse.

When in doubt, run full-enrichment (if your account has it) — it chains the right agents in the right order.

A typical workflow

Most customer workflows follow the same shape:

1. Bring a list of companies in (a CSV, usually exported from Salesforce or a prospecting tool).

2. Dispatch one or more enrichment agents against the list.

3. Poll until the run is complete.

4. Export the enriched data back out.

In practice, with an agent driving the CLI, the whole thing is a single sentence: "Enrich these 500 companies and give me back a CSV with headcount and revenue."

What you can ask for

Once the CLI is set up and pointed at Claude Code (see For agents below), you describe outcomes in plain English. Representative requests:

"Enrich the companies in prospects.csv and give me back a CSV with headcount and revenue."

"Take this list, clean it against our CRM, and flag anything that looks like a duplicate."

"Find every account we have with more than 500 employees in Germany, then enrich them and export the result."

"Look up KERN ID 1234567890 and summarise what we know."

The agent chooses the right commands, dispatches them, polls until the work is complete, and returns the output.

Running commands directly

If you prefer to run commands by hand — for scripting, or just to understand what the agent is doing — the CLI exposes the primitives directly. The sequence below maps one-to-one onto the four primitives.

kernel import --file prospects.csv        # Import — returns an import ID
kernel run full-enrichment -i <import_id> # Run — returns a run ID, consumes credits
kernel run list <run_id>                  # Poll until completed
kernel export -i <import_id>              # Export — free, always latest

Additional manual commands:

kernel import template                     # See the expected CSV columns
kernel run list                            # All recent runs
kernel lookup 1234567890                   # Look up a single account by KERN ID
kernel accounts filter schema              # See filterable fields and operators
kernel accounts set create "<name>" -f '...'  # Save a reusable set
kernel run full-enrichment --set <set_id>  # Run against a set
kernel export -i <id> --fields name,website,kern_id,headcount,revenue

Always count before dispatching a filter-based run: kernel accounts filter -f '<json>' returns the count without dispatching. Unbounded filters consume credits quickly.

For full options on any command: kernel <command> --help.

---

For agents

This section covers what actually happens when Claude Code runs the setup prompt — what gets installed, what gets loaded, and why it keeps the agent on the rails. If you have not yet run the setup, the prompt is at the top of this page.

The skills that ship with the CLI

The CLI installs a set of skills alongside itself. Each skill is a focused instruction set that teaches an agent how to do one thing against Kernel: how to filter, how to import, how to chain agents in the right order, how to move data from Salesforce into Kernel. They are how the agent stays on the rails instead of guessing.

The public skills available today:

Skill	What it covers
kernel	The entry point. Owns the shared contracts (auth, filter shape, operators, terminology) and routes the agent to the right sub-skill.
kernel-enrichment	Importing CSVs and dispatching enrichment runs. Handles agent ordering (core-research first), run dispatch, and status polling.
kernel-search	Filters, account sets, and exports. Teaches the agent the filter schema and to count before running.
kernel-import-by-id	Re-ingesting accounts by KERN ID. Useful for refreshing a known record without re-importing a full list.
salesforce-cli	Authenticating and querying your Salesforce org via the sf CLI.
salesforce-to-kernel	The full pipeline from Salesforce to Kernel: query Salesforce, shape a CSV, import into Kernel.

Why AGENTS.md matters

The installer places a file at ~/.kernel/AGENTS.md containing the live list of agents your account has access to, plus usage notes specific to your setup. Because the agent list varies by customer, an AI agent should always read this file before dispatching runs. The setup prompt above instructs Claude Code to do so.

If your agent ever appears to be guessing at commands or calling agents that do not exist, the fix is almost always the same: ask it to re-read ~/.kernel/AGENTS.md and the files under ~/.kernel/skills/.

---

Keeping the CLI up to date

When a new version is released, an "update available" notice appears at the top of the CLI output. Update with:

kernel update

Troubleshooting & FAQs

The install completed but kernel is not found. The installer places the binary at ~/.kernel/bin/kernel and adds that directory to your PATH. Open a new terminal window so the PATH change takes effect, or run source ~/.zshrc (or ~/.bashrc). If ~/.kernel/bin/kernel --help works but kernel --help does not, it is a shell configuration issue.

The install script failed, or curl is blocked on my work machine. Some corporate environments block the install script or the Node.js download. Contact your Kernel representative — we can provide the tarball directly or help your IT team approve the install URL.

kernel login opens a browser but nothing happens after I sign in. Usually a redirect issue. Close the browser tab, run kernel reauth to clear the partial session, and try again. On a remote machine without a browser (SSH, devbox), contact your Kernel representative for a device-code flow.

How do I confirm I am logged into the right account? Run kernel --help. The authenticated user and organization appear at the top of the output. To switch, run kernel signout followed by kernel login.

How do I switch organizations? Your organization is set from your Kernel account, so switching usually means signing in as a different user. If you work across multiple Kernel tenants, contact your Kernel representative to set up the right access.

How does Claude Code know which agents I have access to? The installer places a file at ~/.kernel/AGENTS.md listing the live set of agents available on your account, along with usage notes. The setup prompt in the For agents section instructs Claude Code to read this file.

Claude Code appears to be guessing at commands. Usually means the installed skills or the local AGENTS.md were not read. Ask the agent to re-read ~/.kernel/AGENTS.md and the files under ~/.kernel/skills/.

Where are my credentials stored? Locally, under ~/.kernel/. They are not synced anywhere else. kernel signout removes them.

How do I update the CLI? Run kernel update. An "update available" notice also appears at the top of the CLI output when a new version is released.

How do I uninstall? Delete the ~/.kernel/ directory and remove the PATH line the installer added to your shell configuration (~/.zshrc or ~/.bashrc).

Something is not working and I need help. Share the import ID or run ID from the command output with your Kernel representative. These two IDs are sufficient to trace any workflow end to end.

Where to go next

• Inbound API — for event-driven enrichment from your own systems, see Inbound API.

• Bulk Retrieval API — for pulling enriched data into a warehouse, see Bulk Retrieval API.

• Command reference — run kernel <command> --help for full options on any command.