# 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**](#for-humans) — a plain-English explanation of what the CLI is, how it works, and what you can do with it.
* [**For agents**](#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:

```bash
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:

```bash
kernel --help
```

### Log in

Authenticate once per machine:

```bash
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](#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.

```bash
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:

```bash
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-fastest-path-paste-this-into-claude-code).

### 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:

```bash
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](https://docs.kernel.ai/developer/inbound-api).
* **Bulk Retrieval API** — for pulling enriched data into a warehouse, see [Bulk Retrieval API](https://docs.kernel.ai/developer/bulk-retrieval-api).
* **Command reference** — run `kernel <command> --help` for full options on any command.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kernel.ai/developer/cli-getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.