ocean-agent-cli

Ocean.io in your terminal — and in your AI assistant.
Search companies & people, enrich profiles, reveal emails/phones, and build GTM pipelines from the CLI or MCP.

Install · Quick start · AI agents · MCP · Ocean API docs · Agent playbook

What is Ocean.io?

Ocean.io is a B2B GTM intelligence platform. It helps sales and marketing teams find lookalike companies, search 67M+ company profiles and 250M+ people, enrich account data, and reveal contact details — via the web app or API.

Get an API token under Settings → API tokens in the Ocean app.

What is ocean-agent-cli?

ocean-agent-cli is an open-source CLI and MCP server for the Ocean.io API. It mirrors the architecture of instantly-cli: one command definition powers both terminal usage and MCP tools.

Audience	What you get
Developers	Scriptable search, enrich, lookup, and reveal workflows with JSON or pretty output
RevOps / GTM	Terminal access to Ocean without writing HTTP clients
AI agents	18 MCP tools (Claude, Cursor, Windsurf, VS Code) — search, enrich, reveal, autocomplete
Automation	Stdout JSON, exit codes, `--quiet`, and webhook-based async bulk jobs

Coverage: 20 API commands across search (v3), enrich, lookup, reveal, warmup, autocomplete, credits, and data-fields. v2 search remains in the CLI for backwards compatibility but is hidden from help and MCP.

Install

npm (recommended)

npm install -g ocean-agent-cli

npx (zero install)

npx ocean-agent-cli credits balance --pretty

From source

git clone https://github.com/bcharleson/ocean-agent-cli.git
cd ocean-agent-cli
npm install && npm run build
npm link   # optional: install `ocean` globally

Requires Node.js 18+.

Authentication

Credentials are checked in this order:

--api-token flag on any command
OCEAN_API_TOKEN environment variable
Stored config at ~/.ocean/config.json (from ocean login)

# Interactive — validates token and saves config
ocean login

# Non-interactive
ocean login --api-token your-token-here

# Environment variable (best for CI and agents)
export OCEAN_API_TOKEN=your-token-here

# Remove stored token
ocean logout

Config file format:

{ "api_token": "your-token-here" }

Quick start

Human workflow — find and enrich a prospect

# Check credits before bulk work
ocean credits balance --pretty

# Discover valid filter field names
ocean data-fields list

# Search VP Sales at US companies in Automotive
ocean search people \
  --people-filters '{"jobTitleKeywords":{"anyOf":["VP Sales"]},"countries":["us"],"seniorities":["Director"]}' \
  --companies-filters '{"industries":["Automotive"]}' \
  --limit 10 --pretty

# Enrich one company (sync)
ocean enrich company --domain tesla.com --pretty

# Enrich one person by LinkedIn (sync)
ocean enrich person --linkedin "https://linkedin.com/in/example" --pretty

Typical sourcing pipeline

ocean data-fields list
ocean autocomplete job-titles --query "vp sales"
ocean search people --people-filters '...' --limit 50
ocean reveal emails --ocean-ids "id1,id2" --webhook-url "https://yourapp.com/hooks/ocean"

Always run ocean credits balance before large searches or reveals. Check dailyLimitRateLeft for remaining API calls today.

For AI agents

If you are an LLM or coding agent using this repo or MCP:

Read OCEAN.md — filter shapes, webhook rules, MCP tool names, common mistakes.
Read AGENTS.md — architecture, env vars, contributor notes.
Prefer v3 search (search_companies, search_people). Do not use v2 search tools — they are not registered in MCP.
Call data_fields_list before building filters; use autocomplete_* to normalize titles and locations.

jobTitleKeywords must be an object, not an array:

{"jobTitleKeywords":{"anyOf":["VP Sales"]},"countries":["us"]}

Webhook required for async bulk: enrich_companies, enrich_people, reveal_emails, reveal_phones.
Domains must be plain hostnames (tesla.com), not URLs with https:// or paths.

MCP tools (18)

Tool	Purpose
`credits_balance`	Search / email / phone credits and daily rate limit
`data_fields_list`	Valid filter field names for search
`search_companies`	v3 company search
`search_people`	v3 people search
`enrich_company`	Single company by domain (sync)
`enrich_person`	Single person by LinkedIn / email / name (sync)
`enrich_companies`	Bulk companies (async + webhook)
`enrich_people`	Bulk people (async + webhook)
`lookup_companies`	By domain
`lookup_people`	By LinkedIn handle or Ocean ID
`reveal_emails`	Async + webhook
`reveal_phones`	Async + webhook
`warmup_companies`	Pre-fetch company data
`autocomplete_companies`	Company name suggestions
`autocomplete_job_titles`	Job title suggestions
`autocomplete_locations`	Location suggestions
`autocomplete_keywords`	Keyword suggestions
`autocomplete_skills`	Skill suggestions

CLI command names use spaces (ocean search people); MCP tool names use underscores (search_people).

Global options

Option	Description
`--api-token <token>`	Override env var / stored config
`--output json\|pretty`	Output format (default: `json`)
`--pretty`	Shorthand for `--output pretty`
`--quiet`	Suppress stdout (exit code only)
`--fields <fields>`	Comma-separated fields (`ocean data-fields list` for names)

Errors print structured JSON with error and code fields (not raw stack traces in default mode).

Commands

Credits & data fields

ocean credits balance
ocean credits balance --pretty
ocean data-fields list

Search (v3 — recommended)

Pass filters as JSON on --companies-filters and/or --people-filters. --filters is an alias for the primary filter flag on each subcommand.

# Companies
ocean search companies \
  --companies-filters '{"industries":["Automotive"],"countries":["us"],"headcountMin":100}' \
  --limit 20

ocean search companies \
  --companies-filters '{"domains":["roush.com","tesla.com"]}' \
  --fields name,domain,employeeCountLinkedin

# People
ocean search people \
  --people-filters '{"jobTitleKeywords":{"anyOf":["VP Sales"]},"countries":["us"],"seniorities":["Director"]}' \
  --limit 50

ocean search people \
  --people-filters '{"jobTitleKeywords":{"anyOf":["engineer"]},"seniorities":["manager"]}' \
  --companies-filters '{"domains":["roush.com","rivian.com"]}'

# Pagination — pass searchAfter from the previous response (opaque cursor string)
ocean search companies \
  --companies-filters '{"industries":["Automotive"],"countries":["us"]}' \
  --limit 50 \
  --search-after "NoWgjANARA0l..."

Enrich

Single record (sync, no webhook):

ocean enrich company --domain tesla.com
ocean enrich company --domain stripe.com --pretty

ocean enrich person --linkedin "https://linkedin.com/in/satyanadella"
ocean enrich person --ocean-id "<ocean-person-id>"
ocean enrich person --name "Jane Doe" --company-domain acme.com

Use plain domains only (tesla.com), not full URLs.

Bulk (async — requires --webhook-url):

ocean enrich companies \
  --domains "stripe.com,twilio.com" \
  --webhook-url "https://yourapp.com/webhooks/ocean"

ocean enrich people \
  --linkedin-urls "https://linkedin.com/in/johndoe,https://linkedin.com/in/janedoe" \
  --webhook-url "https://yourapp.com/webhooks/ocean"

ocean enrich people \
  --ocean-ids "id1,id2" \
  --webhook-url "https://yourapp.com/webhooks/ocean"

Lookup

ocean lookup companies --domains "roush.com,stripe.com"
ocean lookup people --linkedin-handles "satyanadella,johndoe"
ocean lookup people --ocean-ids "id1,id2"

Reveal (async — requires `--webhook-url`)

Results are delivered to your webhook URL.

ocean reveal emails \
  --ocean-ids "id1,id2" \
  --webhook-url "https://yourapp.com/webhooks/ocean"

ocean reveal phones \
  --ocean-ids "id1" \
  --webhook-url "https://yourapp.com/webhooks/ocean"

Warmup

ocean warmup companies --domains "hubspot.com,salesforce.com"

Autocomplete

ocean autocomplete companies --query "Tesla"
ocean autocomplete job-titles --query "vp eng"
ocean autocomplete locations --query "San Francisco"
ocean autocomplete keywords --query "saas"
ocean autocomplete skills --query "python"

MCP server

Every non-deprecated command is available as an MCP tool. Start the local stdio server:

ocean mcp

Cursor / Claude Desktop / VS Code

Global install:

{
  "mcpServers": {
    "ocean": {
      "command": "ocean",
      "args": ["mcp"],
      "env": { "OCEAN_API_TOKEN": "your-token-here" }
    }
  }
}

Without global install:

{
  "mcpServers": {
    "ocean": {
      "command": "npx",
      "args": ["ocean-agent-cli", "mcp"],
      "env": { "OCEAN_API_TOKEN": "your-token-here" }
    }
  }
}

Hosted MCP (no local process)

https://api.ocean.io/mcp/?api-token=<your-token>

Use this URL in clients that support remote MCP endpoints.

API reference

CLI command	Method	Endpoint
`credits balance`	GET	`/v2/credits/balance`
`data-fields list`	GET	`/v2/data-fields`
`search companies`	POST	`/v3/search/companies`
`search people`	POST	`/v3/search/people`
`enrich company`	POST	`/v2/enrich/company`
`enrich companies`	POST	`/v2/enrich/companies`
`enrich person`	POST	`/v2/enrich/person`
`enrich people`	POST	`/v2/enrich/people`
`lookup companies`	POST	`/v2/lookup/companies`
`lookup people`	POST	`/v2/lookup/people`
`reveal emails`	POST	`/v2/reveal/emails`
`reveal phones`	POST	`/v2/reveal/phones`
`warmup companies`	POST	`/v2/warmup/companies`
`autocomplete companies`	POST	`/v2/autocomplete/companies`
`autocomplete keywords`	POST	`/v2/autocomplete/keywords`
`autocomplete job-titles`	POST	`/v2/autocomplete/job-titles`
`autocomplete locations`	POST	`/v2/autocomplete/locations`
`autocomplete skills`	POST	`/v2/autocomplete/skills`

Search base URL: https://api.ocean.io/v3/
All other endpoints: https://api.ocean.io/v2/
Auth header: X-Api-Token: <your-token>

Full API documentation: app.ocean.io/docs

Development

git clone https://github.com/bcharleson/ocean-agent-cli.git
cd ocean-agent-cli
npm install
npm run dev -- credits balance --pretty   # run from source via tsx
npm test
npm run typecheck
npm run build                             # outputs to dist/

Project layout

src/
  index.ts          # CLI entry (commander)
  mcp.ts            # MCP entry
  core/             # auth, client, handler, output, validation
  commands/         # one file per API command

Links

Resource	URL
GitHub	github.com/bcharleson/ocean-agent-cli
npm	npmjs.com/package/ocean-agent-cli
Ocean.io	ocean.io
Ocean API docs	app.ocean.io/docs
Agent playbook	OCEAN.md
Contributor guide	AGENTS.md

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
assets		assets
src		src
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
OCEAN.md		OCEAN.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

ocean-agent-cli

What is Ocean.io?

What is ocean-agent-cli?

Install

npm (recommended)

npx (zero install)

From source

Authentication

Quick start

Human workflow — find and enrich a prospect

Typical sourcing pipeline

For AI agents

MCP tools (18)

Global options

Commands

Credits & data fields

Search (v3 — recommended)

Enrich

Lookup

Reveal (async — requires --webhook-url)

Warmup

Autocomplete

MCP server

Cursor / Claude Desktop / VS Code

Hosted MCP (no local process)

API reference

Development

Project layout

Links

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Reveal (async — requires `--webhook-url`)

Packages