> ## Documentation Index
> Fetch the complete documentation index at: https://www.landbase.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# What Can You Do with the Landbase CLI?

> Choose a Landbase CLI workflow for finding audiences, enriching records, importing contacts, launching campaigns, or exporting datasets.

# What Can You Do with the Landbase CLI?

Landbase CLI turns GTM outcomes into commands you can run from a terminal, Claude Code, Codex, or your own scripts. Choose the path that matches what you want to accomplish:

* [Find and refine an audience](#find-audiences-with-natural-language), then save it for analysis.
* [Match or enrich records](#match-a-person-or-company), including contact email and phone enrichment.
* [Process your own data](#upload-your-own-spreadsheet), from upload through workflow and download.
* [Import contacts or launch outreach](#select-an-account-onboard-and-import-contacts), after choosing an account.
* [Automate repeated work](#chain-commands-into-a-full-pipeline) with sessions, scripts, and structured JSON.

If you have not installed the CLI yet, start with [Install Landbase CLI](https://www.landbase.com/docs/install.md). For agent-led work, see [Use Landbase CLI in Claude Code and Codex](https://www.landbase.com/docs/guides/cli/landbase-cli.md).

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=<label>` 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.

## Choose an enrichment path

Choose the command based on the input you have and where you want the result to go:

| You have | Use | What it does |
| - | - | - |
| One person or company identifier | `enrich` | Returns person or company attributes immediately. |
| A batch of known contacts | `workflow contact-enrich` | Creates an asynchronous enriched child dataset with email and phone data. |
| An existing dataset with many rows | `workflow enrich` | Creates an enriched child dataset with lineage. |

Use `enrich` for one-off lookups, `workflow contact-enrich` for contact discovery, and `workflow enrich` when you need repeatable, dataset-scale processing. The commands are not interchangeable: they accept different inputs and produce different kinds of output.

## 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 the dataset workflow when you have a dataset of known contacts and want asynchronous email or phone enrichment. The removed `contact-enrich submit|get` command no longer accepts raw JSONL leads; see the [migration reference](https://www.landbase.com/docs/reference/cli/contact-enrich.md).

```bash theme={null}
landbase-cli upload ./leads.csv --name="Leads"
landbase-cli workflow onboard <uploaded-dataset-id> --wait
landbase-cli workflow contact-enrich <onboarded-dataset-id> --enrich-phone --wait
```

Both email and phone enrichment run by default. Use `--enrich-phone` for phone-only opt-in behavior, or use the explicit `--enrich-email` and `--enrich-phone` flags when selecting channels. The workflow creates an enriched child dataset and returns a workflow run ID for polling.

```bash theme={null}
landbase-cli workflow wait <workflow-run-id>
landbase-cli workflow publish <enriched-dataset-id> --format=csv --wait
landbase-cli datasets download <published-dataset-id> ./enriched.csv
```

Use `--overwrite-existing` to replace existing contact values. Use `--row-slice=START:END` to process a half-open slice of rows; run slices serially and recombine them with `workflow union` without dedupe keys.

## 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":"<dataset-id>","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=<id>`.

## 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_<order>` (LinkedIn) → `messages` → `coverage` → `launch`. Sending inboxes and LinkedIn accounts are connected in the web app. See [How to launch a campaign](https://www.landbase.com/docs/guides/cli/launch-a-campaign.md).

A campaign can also be **assigned to a teammate** so their inboxes or LinkedIn account send: list assignable users with `account users`, then pass `assignedUserId` at create time or re-assign the draft with `assign --campaign <id> --user <identityId>`. Launching a campaign assigned to someone other than its creator asks for `--yes`. See the [email-campaigns](https://www.landbase.com/docs/reference/cli/email-campaigns.md#email-campaigns-assign) and [linkedin-campaigns](https://www.landbase.com/docs/reference/cli/linkedin-campaigns.md#linkedin-campaigns-assign) references.

## Create dialer sessions

Turn an imported contact tag into a calling session. The JSON definition names
the tag through `audience.tagName` or `audience.tagId`, controls enrichment,
and can assign the session to a teammate with `assignedUserId`.

```bash theme={null}
landbase-cli dialer-sessions create --json session.json
landbase-cli dialer-sessions status 9
```

Use `account users` to find the optional `assignedUserId`; omit it to own the
session yourself. `status` returns the owner and live contact counts grouped by
dial status. See the [dialer-sessions reference](https://www.landbase.com/docs/reference/cli/dialer-sessions.md).

## 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 <dataset-id> --include-runs
landbase-cli datasets lineage <dataset-id> --direction=children
landbase-cli datasets download <dataset-id> ./output.parquet
landbase-cli datasets delete <dataset-id> --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 <dataset-id> --wait
landbase-cli workflow match <dataset-id> --wait
landbase-cli workflow enrich <dataset-id> --company-fields=industry,size_range --wait
landbase-cli workflow publish <dataset-id> --format=csv --wait
landbase-cli workflow sketch <dataset-id> --taxonomy-hints=fintech,healthcare --wait
landbase-cli workflow status <dataset-id>
```

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

For dataset-scale contact enrichment, first upload and onboard a CSV or Excel file, then run `workflow contact-enrich` on the onboarded dataset. Use `workflow wait` to recover the output dataset ID before continuing to publish or download.

## 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=<label-or-session-id>
landbase-cli runs get <run-id> --session=<label-or-session-id>
```

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  # legacy mode only; platform mode uses browser OAuth or S2S auth
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[=<path>]` | You want search results saved locally. |
| `--session=<label>` | 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=<seconds>` | You need to raise or lower the request timeout. |
| `--verbose` | You want request and response details printed to stderr. |
| `--wait` | You want a workflow command 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`.


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