Command Line

ark is the official command line client for the AI-Ark API. It turns people
search, company search, email and phone finding, personality analysis and
credit checks into terminal commands that print JSON, a table or CSV.

It is a single static binary. Every call goes to https://api.ai-ark.com with
your own API key and is billed to your account like any other API call.

Requirements

Install

Download the archive for your platform from the
releases page, unpack it and
put ark on your PATH:

# Linux / macOS. Archives: ark_<version>_<linux|darwin>_<amd64|arm64>.tar.gz
v=1.0.0
curl -sLO https://github.com/ai-ark-com/ark-cli/releases/download/$v/ark_${v}_linux_amd64.tar.gz
curl -sLO https://github.com/ai-ark-com/ark-cli/releases/download/$v/checksums.txt
sha256sum --check --ignore-missing checksums.txt
tar xzf ark_${v}_linux_amd64.tar.gz && sudo mv ark /usr/local/bin/

On Windows unpack ark_<version>_windows_amd64.zip and add the folder to
PATH. Every release ships checksums.txt with the SHA-256 of each archive.

With a Go toolchain:

go install github.com/ai-ark-com/ark-cli@latest
# the binary is named ark-cli; rename or alias it to ark

Confirm the install:

ark version

Authentication

Create an API key in the
API Management Dashboard,
then store it:

ark auth login

The prompt does not echo. The key is checked against the API before it is
saved to the OS keychain (macOS Keychain, Windows Credential Manager, libsecret
on Linux). The key is never written to a file and never printed.

Check what the CLI will use:

ark auth status

Host:    https://api.ai-ark.com
Token:   configured (keychain)
Balance: 1250 credits

Remove the stored key:

ark auth logout

Credential precedence

1. ARK_API_TOKEN environment variable
2. OS keychain (ark auth login)

The environment variable always wins. Use it in CI, in containers and on
servers without a desktop session, where no keychain is available.

export ARK_API_TOKEN=your-key    # in CI, from a secret store
ark credits

📘

Piping the key

ark auth login also reads the key from stdin, so a secret manager can feed
it without the key ever appearing in shell history:
op read op://vault/ai-ark/token | ark auth login

Options

Flags belong to each command. These appear on most of them:

First call

Preview a query before paying per result. A preview costs 1 credit per page,
whatever the page size:

ark people preview --location Germany --seniority c_suite,vp --industry "software development"

Run it for real (0.5 credits per result):

ark people search --location Germany --seniority c_suite,vp --industry "software development" --size 25

Look up allowed values and your balance (free):

ark catalog                        # the catalogs
ark catalog seniority              # values of one filter
ark catalog industries --search health
ark credits

Commands

ark <command> --help lists every flag with its meaning.

Filters

Every filter of the search request body has a flag; the full mapping is in
FILTERS.md.
Flags are ANDed. Comma separated values inside one flag are ORed. Each list
filter comes in four forms:

Text filters (--title, --industry, --skill, --technology, --product,
--keyword, --company-name, ...) honour --match smart|word|strict.

Ranges are written 51-200, 1000+, -50, with k, m and b suffixes
(--revenue 1m-10m). Tenure uses years and months (--tenure-company 1y6m+),
growth uses signed percentages (--headcount-growth marketing:10..15:SIX).

# people
ark people search --current-title "head of sales" --seniority head,vp,director
ark people search --department engineering_technical --skill kubernetes,terraform --match word
ark people search --keyword "carbon accounting" --keyword-source HEADLINE,SUMMARY
ark people search --badge HIRING --language german --exclude-location Berlin

# people filtered by employer: company flags take a company- prefix
ark people search --company-domain stripe.com,adyen.com --seniority c_suite
ark people search --industry "financial services" --employees 51-200,201-500 --founded 2015+

# companies
ark company search --industry "software development" --location Germany --revenue 10m-100m
ark company search --technology hubspot --exclude-technology salesforce --near 52.52,13.405 --radius 25
ark company search --lookalike raisin.com,https://www.linkedin.com/company/n26 --location Germany

--dry-run prints the JSON body the CLI would send, so you can copy it into
a direct API call or check a filter combination for free.

Output and scripting

Output formats

Table and CSV flatten each result into dotted paths (profile.first_name,
company.summary.name). Pick your own with --columns:

ark people search --location Germany --seniority c_suite -o csv \
  --columns id,profile.first_name,profile.last_name,profile.title,company.summary.name > leads.csv

Responses that are not a result page (a single person, a job submission) are
always printed as JSON.

stdout and stderr

stdout carries data only. With table and csv the match count and the
credits used go to stderr, so stdout can be redirected. Errors are one line on
stderr, prefixed with error::

error: token rejected by API: 401 Unauthorized

Exit codes

Piping to jq

Use -o json and take what you need:

ark people search --location Germany --seniority c_suite -o json | jq -r '.content[].id'
ark people search --location Germany --seniority c_suite -o json | jq -r '.trackId'
ark credits -o json | jq .total

Branching on exit codes

#!/usr/bin/env bash
ark people enrich https://www.linkedin.com/in/john-doe -o json > person.json
code=$?
case $code in
  0) echo "found: $(jq -r '.email.output[0].address' person.json)" ;;
  3) echo "no email for this person" ;;
  4) echo "out of credits"; exit 1 ;;
  6) echo "check the API key"; exit 1 ;;
  *) echo "failed with exit code $code"; exit 1 ;;
esac

🚧

set -e

With set -e a non-zero exit aborts the script before your case runs.
Capture the code as shown, or use if ! ark ...; then.

Async jobs: webhook and polling

Bulk export and email finding are asynchronous. Submitting returns a
trackId; the API POSTs to your --webhook URL when the job is done. The
webhook must be a public HTTPS URL (loopback and http are rejected). You
don't have to serve it: poll status until the state is DONE, then read
results.

track=$(ark people export --industry "software development" --seniority c_suite \
  --size 500 --webhook https://example.com/hook | jq -r .trackId)

until ark people export status "$track" | jq -e '.state == "DONE"' >/dev/null; do
  sleep 30
done
ark people export results "$track" --size 100 -o csv > people.csv

results answers HTTP 409 (exit code 1) while the job is still running.

Common workflows

Size a market before spending credits

Preview costs 1 credit per page regardless of size and returns the total
match count. Narrow the query until the count is right, then search:

ark people preview --industry "software development" --location Germany
ark people preview --industry "software development" --location Germany --seniority c_suite,vp
ark people preview --industry "software development" --location Germany --seniority c_suite,vp --employees 51-200
ark people search  --industry "software development" --location Germany --seniority c_suite,vp --employees 51-200 --size 100

Find emails for a search

Search, then submit its trackId to the email finder. The trackId works once
and expires after 6 hours. 1 credit per found email, nothing for misses.

ark people search --location Germany --seniority c_suite --size 100 -o json > search.json
ark people emails find "$(jq -r .trackId search.json)" --webhook https://example.com/hook
ark people emails status <track-id>                    # until "state": "DONE"
ark people emails results <track-id> -o csv > emails.csv

Search and find emails in one job

Up to 10,000 people per job. 0.5 credits per person plus 0.5 per found email.

ark people export --industry retail --location "United States" --seniority director \
  --size 2000 --webhook https://example.com/hook
ark people export list                                 # your submissions and their refunds

Enrich one person at a time

For CRMs, spreadsheets and Clay. --clay selects the V2 endpoints, which
answer HTTP 200 with "data": null instead of exit code 3 when nothing is
found:

ark people enrich https://www.linkedin.com/in/john-doe
ark people enrich 592439b8-13c7-e31c-296e-b6e2f7339aeb --clay
ark people phone --domain stripe.com --name "Patrick Collison"
ark people reverse-lookup [email protected]
ark people reverse-lookup +14155550100
ark people personality https://www.linkedin.com/in/john-doe

Leave out people you already contacted

Suppression lists hold ids of people or companies to exclude from a search.
They are free, hold up to 10,000 ids and expire after 24 hours.

ark people search --industry retail -o json | jq -r '.content[].id' \
  | ark lists create --type people --from-file -        # prints the list id
ark people search --industry retail --exclude-list <list-id>
ark lists update <list-id> --values <id>,<id>            # append; --replace overwrites

Use a hand written request body

Anything the API accepts can be sent as is. The same filter and size checks
apply:

ark company search --dry-run --industry fintech --location Berlin > body.json
ark company search --body body.json
cat body.json | ark company search --body -

Rate limits

The request rate depends on your subscription plan. When the API answers
429, the command retries up to three times, honouring Retry-After, then
exits with code 5.

Shell completion

ark ships completion for bash, zsh, fish and PowerShell:

source <(ark completion bash)                 # current shell
ark completion zsh > "${fpath[1]}/_ark"       # zsh, then restart the shell
ark completion fish > ~/.config/fish/completions/ark.fish
ark completion powershell | Out-String | Invoke-Expression

ark completion <shell> --help shows where to install it permanently.

Security notes

• The key lives only in the OS keychain or ARK_API_TOKEN; the CLI never
  logs, prints or stores it elsewhere.
• Redirects are refused, so the key cannot be forwarded to another host.
• ARK_BASE_URL must be https; when set, the host is shown on stderr with
  every call.
• CSV cells starting with =, +, - or @ are quoted so spreadsheets do
  not run them as formulas.

Next

• API Reference
• Filter reference for the CLI
• MCP Server
• Source and issues