Skip to main content

​
Installation

​
”command not found: deepline”

Your shell cannot find the deepline binary. This usually means the install directory is not on your PATH. Most common cause: You installed Deepline but did not reload your shell configuration.
If which deepline returns nothing, ask your agent to follow the installation guide for the current environment:
For a direct terminal repair: check npm --version and use the matching command. For npm 11.16 or newer:
For older npm:
If the global npm prefix is not writable, install into the project instead:
On macOS with Homebrew: If you installed via a non-standard method, check that /usr/local/bin or ~/.local/bin is in your PATH:

​
npm install hangs or fails

Most common cause: Corporate firewalls, VPNs, or proxy servers blocking npm downloads.
If you are behind a proxy, set the standard environment variables before installing:
For the project-local install, run the executable at ./.deepline/runtime/bin/deepline.

​
Authentication

​
CLI auth works, but a raw HTTP request is unauthorized

deepline auth status does not export DEEPLINE_API_KEY to the current shell. The command confirms that the CLI can use stored credentials for its configured host. Use the CLI command when one exists. CLI authentication does not authenticate a separate curl, Python, or JavaScript request. If you need a raw HTTP request, use the documented API authentication procedure for the endpoint. Verify the target host and workspace. Do not print, paste, or log a stored key.

​
”Missing DEEPLINE_API_KEY. Run: deepline auth register”

The CLI requires an API key for every authenticated command. This error means no key was found in your environment.
After completing the browser flow, verify your connection:
You should see Status: active and your workspace name. If the browser flow does not complete: Some email security tools (Mimecast, Barracuda, etc.) intercept magic links and consume them before you can click. If you see Status: not connected after clicking the link:
Open the link in a private/incognito browser window to bypass email security scanners.

​
”Status: unauthorized” after authenticating

The CLI returned a 401 or 403 when checking your credentials.
Common causes:
  1. Your API key expired or was rotated by an org admin.
  2. You were removed from the workspace. Ask your org admin to re-invite you.
  3. You are authenticated to the wrong workspace. Run deepline auth status and check the Workspace field.

​
Auth status returns “Auth status error (status …)”

A server-side issue prevented the auth check. Retry after a few seconds:
If the error persists, check status.deepline.com for service incidents.

​
Enrichment

​
”No results” for contacts I know exist

Most common cause: A single provider does not have coverage for your target contacts. Use waterfall enrichment across multiple providers instead.
Provider coverage varies by geography, industry, seniority, input quality, and validation policy. Run the maintained Play on a representative pilot. Review accepted results, no results, failures, and charges before you estimate the full input.

​
Enrichment runs but emails bounce

Most common cause: The result was not checked against the validation policy you need before it reached a sequencer. Find a maintained Play that returns the validation fields you require, inspect it, and run a small pilot:
Use the returned Play name with deepline plays describe, then review its validation output and no-result states before sending a larger list.

​
Credits consumed but no data returned

Most common cause: The tool’s pricing unit charges for a request, page, or other work that can occur before a match. Do not infer billing behavior from an empty result. Inspect the current Play or tool contract and the completed run. To avoid wasting credits on large lists, always run a pilot first:
If the pilot returns no data, check:
  1. Your input fields satisfy the Play contract.
  2. The provider route supports your target geography and industry.
  3. The run output identifies a provider failure or a no-result state.

​
”Invalid Play input”

This means the value passed with --input or --csv does not match the Play’s declared contract. Inspect the contract before changing flags:
For structured scalar input, wrap valid JSON in single quotes:
For custom logic, have your coding agent inspect the maintained Play contract and author an owned Play with the Deepline SDK. Check the complete local module graph before running it. Source export is not a dependency-aware scaffold for maintained Plays that import sibling modules.

​
”Unknown tool <tool_id>”

The tool ID you specified does not exist. Check available tools:
Tool IDs are case-sensitive. Common mistakes: Apollo_People_Match (wrong) vs apollo_people_match (correct).

​
Rate limit errors during enrichment

When a provider rate-limits your requests, the CLI automatically retries with backoff. You will see messages indicating the rate limit rule and retry delay. If you consistently hit rate limits:
  1. Process smaller batches (fewer rows per run).
  2. If using BYOK, check your provider account’s rate limit tier.
  3. Review the reported provider rule and retry timing before changing the run.

​
BYOK (Bring Your Own Keys)

​
How do I add my own API keys?

BYOK lets you use your own provider API keys for provider-side usage while Deepline manages the workflow. BYOK keys are managed in the dashboard, not the CLI:
See Bring Your Own Keys for the full setup flow. After connecting a key, enrichment calls to that provider use your key automatically.

​
Provider returns 401/403 with my own key

Most common cause: The key does not have the required permissions or your provider account tier does not include API access. Check these in order:
  1. Key is valid: Test the key directly against the provider’s API (e.g., curl to Apollo’s endpoint with your key).
  2. API access enabled: Some provider plans (especially free tiers) do not include API access. Check your provider dashboard.
  3. Rate limits: Your key may have a lower rate limit than Deepline’s default throughput. The CLI surfaces the rate limit error with provider and rule details.
  4. Key format: Ensure there are no trailing spaces or newlines. Re-set the key in the dashboard at https://code.deepline.com/dashboard/keys. See Bring Your Own Keys.

​
Claude Code / Skills

​
/deepline-gtm or Deepline skill not recognized in Claude Code

Most common cause: The Deepline skill is not installed or was renamed.
If the skill file exists but Claude Code does not recognize it, restart your Claude Code session. Claude Code reads skill files at session startup. Note: If you previously used a skill called “GTM Meta Skill,” it was renamed to “Deepline.” This rename can cause the skill to disappear from active sessions. Restart Claude Code after updating.

​
Claude Code writes incorrect Deepline commands

Most common cause: The SKILL.md file is out of date or not being read by your agent.
  1. Update to the latest version:
  1. Verify the skill file is current:
  1. Start a new Claude Code session so it picks up the updated skill file.
If a public command disagrees with the live CLI contract, report the page and prefer deepline search, plays describe, and plays check before execution.

​
Database

​
”Where are my enrichment results?”

Deepline stores enrichment results in a managed Neon Postgres database. After an enrichment run completes, your data is available via SQL.
For a database-native tool such as DBeaver, pgAdmin, or Metabase, get the Database URI through the dashboard’s Database Access flow. deepline auth status --reveal reveals no PostgreSQL credentials. See Direct PostgreSQL access for the URI boundary and credential handling.

​
”Missing —sql SQL”

The deepline db query command requires a --sql flag with your SQL statement:

​
Cannot connect from a database-native tool

Most common cause: Incorrect connection string format or network restrictions.
  1. Verify your connection string starts with postgresql:// (not postgres://, which some clients do not accept).
  2. Check your network: Neon Postgres requires outbound connections on port 5432. Corporate firewalls may block this.
  3. IP allowlisting: If your organization has IP restrictions configured, ensure your current IP is allowlisted.
  4. Authentication errors: Return to the dashboard’s Database Access flow, rotate the Database credential if necessary, and update the server-side secret used by the client.

​
Sequencers (Instantly, Lemlist)

​
Push to Instantly or Lemlist fails

Most common cause: Missing or incorrect API key for the sequencer.
See Bring Your Own Keys to connect Instantly, Lemlist, and other sequencer keys. Check these in order:
  1. API key permissions: Ensure your key has write access to campaigns. Read-only keys will return 403.
  2. Campaign ID: Verify the campaign ID exists and is active in your sequencer dashboard. A deleted or paused campaign will reject pushes.
  3. Payload format: Each sequencer expects specific contact fields. Ensure your enrichment output includes at minimum email and first_name.

​
General Errors

​
”Auth error while listing tools. Check DEEPLINE_API_KEY.”

The CLI tried to fetch available integrations but your API key was rejected (401/403).

​
Network errors / timeouts

If commands fail with network-related errors:
  1. Check your internet connection.
  2. Check for VPN/proxy issues:
  1. Check service status: Visit status.deepline.com.

​
Playground backend fails to start

If you see Unable to ensure playground backend is running (exit_code=...):
  1. Check that no other process is using the playground port.
  2. Try stopping and restarting:
  1. Enable debug logging for more details:

​
Still stuck?

Office Hours

Join our weekly office hours (Thursdays) for live help. Bring your screen, we will debug together.

Email Support

Email team@deepline.com with your CLI version (deepline --version), the full error output, and what you were trying to do.