Landbase CLI lets you work with Landbase from your terminal, Claude Code, Codex, or your own scripts. You can ask for audiences in plain English, enrich records, enrich contacts with email and phone data, upload spreadsheets, run dataset workflows, and download structured files for analysis.
Most commands return JSON, which makes the CLI easy for agents and scripts to read. When something goes wrong, the CLI returns a stable error code so your workflow can recover or ask for the right fix.
## Find audiences with natural language
Use the CLI when you want Landbase to build a company or people audience from a plain-English request.
```bash theme={null}
landbase-cli "find 3PL logistics companies in the US" --download=results.jsonl
```
You can also use the explicit `search` command:
```bash theme={null}
landbase-cli search "find AI engineers in London" --download=engineers.jsonl
```
This is the fastest path when you want an agent to:
* Find companies or contacts that match a market, role, location, industry, or signal.
* Save the results to a local file.
* Pass the dataset into another script, notebook, dashboard, or app.
## Use Advanced Dataset Creator for precise audiences
Most searches can use the default agent. When you need custom SQL, aggregations, exact filters, ratios, or output columns, use `--agent=advanced_dataset_creator`.
Advanced Dataset Creator is especially useful for searches like:
* Companies where one team's headcount is low relative to another team's headcount.
* Accounts from an uploaded list that match a computed condition.
* Rankings, counts, or breakdowns that need aggregation.
* Prospect lists where the output columns need to be defined in the prompt.
It uses a two-step flow. First, ask for the dataset and reuse a session label:
```bash theme={null}
landbase-cli search --agent=advanced_dataset_creator --session=sales-ratio \
"Find companies where the AE-to-SDR ratio is between 1.5 and 3.0. Return company name, website, AE count, SDR count, and ratio."
```
Then confirm the proposed query in the same session:
```bash theme={null}
landbase-cli search --agent=advanced_dataset_creator --session=sales-ratio "yes, run it" --download=sales-ratio.jsonl
```
## Keep refining the same search
Add `--session=
` when you want follow-up prompts to continue the same conversation.
```bash theme={null}
landbase-cli "find SaaS companies in London" --session=uk-saas --download=companies.jsonl
landbase-cli "narrow to 50-200 employees" --session=uk-saas --download=companies-filtered.jsonl
```
This is useful when you want to start broad, inspect what came back, and then tighten the audience without starting over.
## Download results in the format you need
The `--download` flag writes search results to disk. If you do not pass a path, it defaults to `./results.jsonl`.
The file extension controls the output:
| Extension | What happens |
| ----------- | ---------------------------------------------------------------------- |
| `.jsonl` | Publishes to JSONL.gz, then unzips it into a ready-to-read JSONL file. |
| `.jsonl.gz` | Publishes to compressed JSONL and keeps it compressed. |
| `.csv` | Publishes to CSV and downloads the published file. |
| `.parquet` | Downloads the native dataset bytes directly, without a publish step. |
Published files can take a few minutes because Landbase runs a publish workflow before the download is ready.
## Match a person or company
Use `match` when you have one record and want Landbase to find the best corresponding person or company.
```bash theme={null}
landbase-cli match person --first-name=Daniel --last-name=Saks --company-website=landbase.com
landbase-cli match company --website=superthread.com
landbase-cli match company --name=Anthropic
```
This is helpful for record cleanup, CRM matching, deduplication, and workflows where you need to turn partial information into a Landbase match.
## Enrich a record
Use `enrich` when you already have a person or company identifier and want more fields back.
```bash theme={null}
landbase-cli enrich --linkedin-url=https://www.linkedin.com/in/danielsaks
landbase-cli enrich --company-website=landbase.com --company-fields=industry,size_range
landbase-cli enrich --linkedin-url=... --company-fields=hq_city,hq_state,hq_country
```
You can request company fields, person fields, or both. If you pass a person identifier, the CLI can automatically resolve the related company and return company enrichment too.
## Enrich contacts with email and phone
Use `contact-enrich` when you have a batch of leads and want asynchronous contact enrichment for emails, phone numbers, or both.
```bash theme={null}
landbase-cli contact-enrich submit ./leads.jsonl --enrich-phone --wait
landbase-cli contact-enrich submit - --wait
landbase-cli contact-enrich get
```
This is different from `enrich`: `enrich` is a synchronous single-record lookup for person and company attributes, while `contact-enrich` starts a batch job and gives you a `request_id`.
Each lead should include either a LinkedIn URL or a name plus a company anchor:
```json theme={null}
{
"first_name": "Hugh",
"last_name": "Hopkins",
"linkedin_url": "https://www.linkedin.com/in/hughhopkins",
"company_domain": "landbase.com"
}
```
You can pass leads as:
| Input | Use it when |
| --------------------- | ---------------------------------------------------------- |
| `.json` | You have a single JSON object or an array of lead objects. |
| `.jsonl` or `.ndjson` | You have one lead object per line. |
| `-` | You want to pipe leads from another command through stdin. |
Email enrichment is on by default. Add `--enrich-phone` when you also want phone numbers, or use `--no-enrich-email --enrich-phone` for phone-only enrichment.
Add `--wait` when you want the CLI to poll until the batch reaches a terminal status. The default polling ceiling is about 10 minutes, and you can override it with `--timeout=`. If the wait times out or is interrupted, the error includes the `request_id`, so you can resume with:
```bash theme={null}
landbase-cli contact-enrich get
```
For larger jobs, keep each batch at or below 100 leads and avoid submitting more than about 10 batches per minute per account.
## Upload your own spreadsheet
Use `upload` to bring a CSV or Excel file into Landbase as a dataset.
```bash theme={null}
landbase-cli upload ./crm_export.csv --name="Q1 CRM"
```
The command returns a dataset ID. You can use that ID to run workflows such as onboard, match, enrich, publish, and download.
## Select an account, onboard, and import contacts
In platform mode (the default), some commands run against a specific Landbase account. Pick which account the CLI uses, fill in its onboarding profile, and bulk-import contacts from a dataset.
First, sign in and choose the account. Run `account set` with no arguments to pick from a list — your choice is saved, so this is a one-time step per machine:
```bash theme={null}
landbase-cli account list
landbase-cli account set
```
Fill in the account's onboarding profile. Run `get` to see which fields are still needed, then submit a partial payload:
```bash theme={null}
landbase-cli onboarding get
echo '{"aboutCompany":{"description":"We sell AI-powered prospecting tools."}}' \
| landbase-cli onboarding update --json -
```
Import the contacts in a dataset into the active account under a tag. `--watch` blocks until the import finishes and prints a summary of what landed:
```bash theme={null}
echo '{"datasetId":"","tagName":"Q2 outreach"}' \
| landbase-cli contacts-import start --json - --watch
```
To target a different account for a single command without changing the saved one, pass `--account=`.
## Launch outbound campaigns
Create and launch outbound **email** and **LinkedIn** campaigns against an imported tag. Both channels share the same shape — create a draft, then launch. A template-mode campaign carries one shared message per step and is ready to launch immediately:
```bash theme={null}
# Email — create from a JSON definition, then launch
landbase-cli email-campaigns create --json campaign.json
landbase-cli email-campaigns launch 123 --watch
landbase-cli email-campaigns status 123
# LinkedIn — same flow, different subcommand
landbase-cli linkedin-campaigns create --json campaign.json
landbase-cli linkedin-campaigns launch 456 --watch
```
For per-contact copy, create in personalized mode and fill the exported audience CSV before launching: `audience` → fill `subject_i`/`body_i` (email) or `message_` (LinkedIn) → `messages` → `coverage` → `launch`. Sending inboxes and LinkedIn accounts are connected in the web app. See [How to launch a campaign](/docs/how-to/launch-a-campaign).
## Manage datasets
Use dataset commands when you need to list, inspect, download, trace, or delete datasets in your workspace.
```bash theme={null}
landbase-cli datasets list
landbase-cli datasets show --include-runs
landbase-cli datasets lineage --direction=children
landbase-cli datasets download ./output.parquet
landbase-cli datasets delete --yes
```
`lineage` is especially useful after workflows because it helps you find the child dataset created by a publish, enrich, match, onboard, or sketch run.
## Run batch workflows
Use `workflow` commands when you want Landbase to process an existing dataset.
```bash theme={null}
landbase-cli workflow onboard --wait
landbase-cli workflow match --wait
landbase-cli workflow enrich --company-fields=industry,size_range --wait
landbase-cli workflow publish --format=csv --wait
landbase-cli workflow sketch --taxonomy-hints=fintech,healthcare --wait
landbase-cli workflow status
```
Add `--wait` when you want the command to block until the workflow completes. Without `--wait`, the CLI returns a workflow run ID that you can poll with `workflow status`.
## Chain commands into a full pipeline
A typical workflow is upload, onboard, publish, find the published child dataset, and download it.
```bash theme={null}
ID=$(landbase-cli upload ./file.csv --name=demo | jq -r .id)
landbase-cli workflow onboard $ID --wait
landbase-cli workflow publish $ID --format=jsonl.gz --wait
CHILD=$(landbase-cli datasets lineage $ID --direction=children --workflow=publish | jq -r '.[0].id')
landbase-cli datasets download $CHILD ./out.jsonl.gz
```
For search results, you can do the common conversion in one command:
```bash theme={null}
landbase-cli "find AI engineers in London" --download=engineers.jsonl
```
If you do not have a LinkedIn URL, match the person first, then pass the matched contact into `contact-enrich`:
```bash theme={null}
DOMAIN=landbase.com
landbase-cli match person --first-name=Hugh --last-name=Hopkins \
--company-website="$DOMAIN" \
| jq --arg domain "$DOMAIN" '.result.candidate | {
first_name: .member_name_first,
last_name: .member_name_last,
linkedin_url: .member_websites_linkedin,
company_domain: $domain
}' \
| landbase-cli contact-enrich submit - --wait --enrich-phone
```
## Inspect previous agent runs
Use `runs` when you need to review prior agent runs for a session.
```bash theme={null}
landbase-cli runs list --session=
landbase-cli runs get --session=
```
Pass the same session label you used with `--session`, or use the raw `session_id` returned by a search response.
## Authenticate and stay current
Use `auth` to sign in, check which key is active, paste an API key, or clear the locally stored key.
```bash theme={null}
landbase-cli auth login
landbase-cli auth login --force
landbase-cli auth login --key
landbase-cli auth status
landbase-cli auth logout
```
Add `--force` to re-authenticate even when a valid session already exists — useful when a stale session keeps causing errors.
Use `update` to self-update to the latest release:
```bash theme={null}
landbase-cli update
```
## Read outputs safely
Search commands return a structured response with fields such as `run_id`, `session_id`, `status`, `content`, `dataset_id`, and `created_at`.
Other commands return the relevant endpoint JSON directly. When you only need a single value, pipe the output through `jq`:
```bash theme={null}
landbase-cli "find fintech startups in NYC" | jq -r .dataset_id
```
## Common options
| Option | Use it when |
| ----------------------------------- | ------------------------------------------------------------------------------------------------ |
| `--download[=]` | You want search results saved locally. |
| `--session=` | You want follow-up searches to continue the same conversation. |
| `--agent=advanced_dataset_creator` | You need custom SQL, aggregations, exact filters, ratios, or custom output columns for a search. |
| `--format=json` or `--format=table` | You want JSON output or a prose-only table view for search. |
| `--timeout=` | You need to raise or lower the request timeout. |
| `--verbose` | You want request and response details printed to stderr. |
| `--wait` | You want workflow commands or `contact-enrich submit` to wait until processing finishes. |
| `--yes` | You are confirming a destructive dataset delete. |
| `--no-update-check` | You want to skip the daily update check for this command. |
## Failure codes
| Exit code | Meaning |
| --------- | ------------------------------------------------------------------------------------------------ |
| `0` | Success. |
| `1` | The command needs a caller fix, such as different flags or a required confirmation. |
| `2` | The API returned an error, a resource was missing, a publish was required, or a download failed. |
| `3` | Authentication failed or no active key was available. |
| `4` | A network or timeout issue occurred. |
Errors are printed to stderr as JSON so agents and scripts can branch on `error.code`.