> ## Documentation Index
> Fetch the complete documentation index at: https://docs-agentic-id.icustomer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> The agentic-id command: single lookups and CSV files from a terminal, with the same caps and checks as the MCP tools.

`agentic-id` runs every Agentic ID product from a terminal. It works on single lookups and on CSV files.

## Install

The command ships with the [Claude Code plugin](https://docs-agentic-id.icustomer.ai/claude-code-plugin.md). It needs Node.js 18 or later and installs no packages.

> [tab] Inside Claude Code
>
> Install the plugin. Claude Code puts `agentic-id` on the PATH of the shells it starts.

> [tab] Any terminal
>
> Clone the plugin repository and link the command into a folder on your PATH.
>
> ```bash theme={null}
> git clone https://github.com/icustomerai/agentic-id-plugin
> ln -s "$PWD/agentic-id-plugin/plugins/agentic-id/bin/agentic-id" /usr/local/bin/agentic-id
> ```

> [!NOTE]
>
> The CLI is not on npm yet.

## Set up

```bash theme={null}
export AGENTIC_ID_URL=https://YOUR_AGENTIC_ID_HOST
agentic-id login      # sign in with your account, in the browser
agentic-id doctor     # checks Node, credential, server and the log folder
```

| Variable | Purpose |
| - | - |
| `AGENTIC_ID_URL` | The Agentic ID API address |
| `AGENTIC_ID_API_KEY` | API key. Used instead of a sign-in when set. |
| `AGENTIC_ID_API_KEY_FILE` | Path of a file that holds the API key, so the key stays out of your shell history |
| `AGENTIC_ID_CONFIG_DIR` | Folder for the session and the usage log. Default `~/.agentic-id` |

`agentic-id login` stores the session in `~/.agentic-id/session.json`. `agentic-id logout` ends it on your machine and on the server. See [Authentication](https://docs-agentic-id.icustomer.ai/authentication.md).

## Commands

| Command | What it does | Charged |
| - | - | - |
| `validate <email...>` | Is each mailbox real | Yes |
| `resolve` | One Agentic ID for a person or company | Yes |
| `enrich` | Fill in missing facts | Yes |
| `find <domain>` | People in a role at one company | Yes |
| `discover` | Companies, and optionally people, that match filters | Yes, except `--count` |
| `lookalike <domain...>` | Companies like your seeds | Yes |
| `facts <id>` | Each fact's level and evidence | No |
| `ledger <id>` | The ID's history, hash chain re-checked | No |
| `estimate <command> [flags]` | The most a command could cost, without calling | No |
| `workspace [n]` | Credits, spend and the last n charges. Alias: `credits`. | No |
| `report <id> --outcome <outcome>` | Report what happened to a value | No |
| `login` | Sign in, in the browser | No |
| `logout` | End the sign-in | No |
| `status` | Which server and workspace. Aliases: `me`, `whoami`. | No |
| `doctor` | Check the setup | No |
| `usage [n]` | Credits per tool and the last n calls from the local log | No |

### Flags for every command

| Flag | Meaning |
| - | - |
| `--max-credits N` | The most the call may charge. Needed for any call that could cost more than 10 credits and for every `--file` run. |
| `--dry-run` | Show what would be sent and the estimate. Send nothing. |
| `--json` | Print the full answer as JSON |
| `--purpose <purpose>` | `b2b_outbound`, `ad_audience`, `own_customer_enrichment` or `fraud_check` |
| `-h`, `--help` | List commands and flags |
| `-v`, `--version` | Print the client version |

### validate

```bash theme={null}
agentic-id validate alex.rivera@acme.example --max-credits 1
```

| Flag | Meaning |
| - | - |
| `--domain <domain>` | Check a company domain: is it live and does it take mail |

### resolve

```bash theme={null}
agentic-id resolve --domain acme.example
agentic-id resolve --name "Alex Rivera" --company "Acme" --max-credits 1
```

| Flag | Meaning |
| - | - |
| `--email`, `--linkedin`, `--name`, `--company`, `--domain` | The identifiers you have |
| `--kind person\|company` | Inferred when omitted |
| `--spend` | Ask paid sources when the ledger cannot resolve it |

### enrich

```bash theme={null}
agentic-id enrich --email alex.rivera@acme.example --fields title,company_name --max-credits 2
```

| Flag | Meaning |
| - | - |
| `--email`, `--linkedin`, `--name`, `--company`, `--domain` | Who to enrich. With no person flag, `--domain` and `--company` enrich the company. |
| `--fields a,b` | Only these fields |

### find

```bash theme={null}
agentic-id find acme.example --role "VP Marketing" --limit 2 --max-credits 4
```

| Flag | Meaning |
| - | - |
| `--role <title>` | Job title. Repeatable. |
| `--seniority <level>` | For example `director+` |
| `--country <code>` | Where the person is. Repeatable. |
| `--limit N` | How many people. Default 5, max 25. |

### discover

```bash theme={null}
agentic-id discover --industry software --country GB --min 100 --max 2000 --count
agentic-id discover --industry software --country GB --max-accounts 10 --max-credits 10
```

| Flag | Meaning |
| - | - |
| `--industry`, `--country`, `--tech`, `--keyword` | Account filters. Repeatable. |
| `--min N`, `--max N` | Employee range |
| `--title <title>`, `--seniority <level>`, `--per-account N` | Also return people in each company |
| `--max-accounts N` | How many companies. Default 25. |
| `--count` | How many match. Nothing is delivered and nothing is charged. |

### lookalike

```bash theme={null}
agentic-id lookalike acme.example globex.example initech.example --max-accounts 10 --max-credits 10
```

| Flag | Meaning |
| - | - |
| `--max-accounts N` | How many companies. Default 25. |

### report

```bash theme={null}
agentic-id report ic-... --outcome bounced --field work_email
```

| Flag | Meaning |
| - | - |
| `--outcome` | `bounced`, `replied`, `wrong_person` or `confirmed` |
| `--field` | Which value the outcome is about. Default `work_email`. |

### estimate

```bash theme={null}
agentic-id estimate discover --country GB --max-accounts 50
```

Worked out on your machine. Nothing is sent.

## CSV files

`validate`, `resolve`, `enrich` and `report` take `--file`. The output keeps every column and row of your file and adds columns. Repeated rows are paid once. Personal emails are not sent.

```bash theme={null}
agentic-id validate --file leads.csv --dry-run
agentic-id validate --file leads.csv --max-credits 200 --out leads.checked.csv
agentic-id resolve  --file leads.checked.csv --max-credits 500 --out leads.clean.csv
```

| Command | Columns added |
| - | - |
| `validate --file` | `email_verdict`, `email_reason` |
| `resolve --file` | `agentic_id`, `resolve_outcome`, `resolve_note`, `same_id_as_row` |
| `enrich --file` | `agentic_id`, `enrich_status`, then `aid_<field>` and `aid_<field>_level` per field |
| `report --file` | `report_status`. The file needs an `agentic_id` column and an `outcome` column. |

| Flag | Meaning |
| - | - |
| `-f`, `--file <path>` | The input CSV |
| `-o`, `--out <path>` | Write the result there instead of stdout. It must not be the input file. |
| `--limit-rows N` | Only the first N rows |
| `--column <name>`, `--email-column <name>` | The email column, when its name is not recognised |
| `--linkedin-column`, `--name-column`, `--company-column`, `--domain-column` | Other identifier columns |

Rules for file runs:

* Every paid file run needs `--max-credits`. Run with `--dry-run` first to see the row count and the estimate.
* When a `resolve --file` run reaches the cap, it stops. The file holds what was done, rows not reached are marked `not_run`, and the exit code is 3.
* `--json` with `--file` needs `--out`. The rows go to the file and the summary is printed as JSON.
* Comma, semicolon and tab separated files are read. Cells that a spreadsheet would run as a formula are written with a leading quote.

## Output

| Mode | What you get |
| - | - |
| Default | The one-line summary, then the rows that matter, as text |
| `--json` | The full answer as JSON |
| `--file` | CSV on stdout, or in `--out`. The summary goes to stderr. |

Errors go to stderr. With `--json` an error is printed as JSON with `error`, `status`, `message`, `fix` and `request_id`. See [Errors](https://docs-agentic-id.icustomer.ai/errors.md).

## Exit codes

| Code | Meaning |
| - | - |
| 0 | OK |
| 1 | Bad input. Nothing was sent. |
| 2 | Credential problem: not signed in, or the key was refused |
| 3 | Credits or cap: not enough credits, a cap is required, or a file run stopped at its cap |
| 4 | Refused by the API |
| 5 | The API did not answer, or failed on its side |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.