instantly-cli

name	instantly-cli
description	Use this skill when an agent needs to operate the Instantly API through the `instantly` CLI. Covers authentication, command discovery, output formats, pagination, JSON-heavy flags, supported resources, and safe command patterns for campaigns, leads, accounts, analytics, emails, webhooks, and related Instantly API v2 operations.
invocable	true
argument-hint	[resource] [action] [flags]

Instantly CLI

Use this skill to work with the installed instantly program.

This is an operator skill, not a repository-maintenance skill. The goal is to help an agent use the CLI correctly to work with the Instantly API.

What This Skill Is For

Use it when you need to:

1. Read or modify Instantly data through the CLI.
2. Translate an Instantly API task into the right instantly <resource> <action> command.
3. Discover the exact flags or actions supported by the installed CLI.

Do not assume the CLI exposes every API endpoint. Always confirm the available commands from the binary itself.

Ground Truth

Use this order when deciding how to act:

1. instantly --help
2. instantly <resource> --help
3. instantly <resource> <action> --help
4. Official docs: https://developer.instantly.ai/

If the CLI and the API docs differ, the CLI help is the source of truth for what the installed binary can do.

Current API Facts

As of April 15, 2026, the official docs indicate:

• API v1 was deprecated on January 19, 2026.
• API keys are scope-based.
• The docs expose both the live API server and a mock server.
• The workspace-wide rate limits are 100 requests per second and 6,000 requests per minute, shared across API keys.

Useful docs:

• Getting Started: https://developer.instantly.ai/getting-started/getting-started
• Rate Limits: https://developer.instantly.ai/getting-started/rate-limit
• Migration Guide: https://developer.instantly.ai/guides/api-v1-migration
• API Explorer: https://developer.instantly.ai/api/v2/supersearch-enrichment

First Steps

Before running a mutating command, inspect help:

instantly --help
instantly campaign --help
instantly campaign create --help

Use help-driven discovery instead of guessing action names or flag names.

Authentication

The CLI supports three common ways to supply the API key:

1. --api-key
2. INSTANTLY_API_KEY
3. Saved config via instantly auth <api-key>

Examples:

instantly auth <api-key>
instantly account list
instantly --api-key <api-key> campaign list
INSTANTLY_API_KEY=<api-key> instantly lead list

If the CLI reports that an API key is required, either pass --api-key explicitly or save it with instantly auth.

Global Flags

Common global flags:

• --api-key, -k
• --output, -o: json, table, csv
• --no-color
• --verbose, -v

Default operating posture:

• Use --output json for agent workflows, parsing, or follow-up automation.
• Use --output table for quick human inspection.
• Use --verbose when debugging request/response failures.

Examples:

instantly campaign list --output json
instantly account list --output table
instantly webhook get --id <uuid> --verbose

Core Command Pattern

Most commands follow this pattern:

instantly <resource> list
instantly <resource> get --id <uuid>
instantly <resource> create ...
instantly <resource> update --id <uuid> ...
instantly <resource> delete --id <uuid>

Important exceptions:

• Some commands key off --email instead of --id, especially accounts.
• Some resources expose action verbs beyond CRUD such as activate, pause, bulk-add, merge, reply, share, duplicate, or sending-status.
• Some successful mutating commands print a confirmation line instead of returning a JSON object.

Supported Top-Level Resources

The installed CLI currently exposes these top-level commands:

• account
• account-campaign-mapping
• analytics
• audit-log
• background-job
• block-list-entry
• campaign
• crm
• custom-tag
• custom-tag-mapping
• email
• email-template
• email-verification
• inbox-placement-analytics
• inbox-placement-report
• inbox-placement-test
• lead
• lead-label
• lead-list
• prompt-template
• sales-flow
• subsequence
• supersearch
• webhook
• webhook-event
• workspace
• workspace-group-member
• workspace-member

If a needed resource is missing from instantly --help, the binary does not currently support it.

Pagination

List-style commands commonly support:

• --limit
• --starting-after
• --all

Guidance:

• Start with a bounded --limit unless you truly need the full dataset.
• Use --all only when you need every page.
• Preserve cursors if you are building a multi-step workflow.

Examples:

instantly campaign list --limit 25
instantly campaign list --starting-after <cursor>
instantly lead list --all --output json

JSON-Heavy Flags

Many useful commands accept nested JSON as a string argument. Do not invent body shapes. Use the official docs and command help to confirm the expected structure.

Common JSON-driven patterns:

• campaign create/update --schedule --sequences
• subsequence create/update --conditions --schedule --sequences
• prompt-template create/update --properties
• sales-flow create/update --queries
• supersearch ... --json
• inbox-placement-test create/update --schedule --recipients-labels --automations
• block-list-entry bulk-create --json
• block-list-entry bulk-delete --json
• custom-tag toggle-resource --filter
• lead create/update --custom-variables

File-driven pattern:

• lead bulk-add --file <path> expects a JSON array of leads

Use single quotes around JSON on Unix-like shells:

instantly lead update --id <uuid> --custom-variables '{"tier":"enterprise"}'
instantly campaign create --name "Q2 Outbound" --schedule '<schedule-json>'
instantly lead bulk-add --campaign-id <uuid> --file ./leads.json

Safe Discovery Workflow

When you know the business task but not the exact command:

1. Find the resource from instantly --help
2. Inspect the resource with instantly <resource> --help
3. Inspect the action with instantly <resource> <action> --help
4. Only then build the command

Example:

instantly webhook --help
instantly webhook create --help

This is the default pattern for every unfamiliar task.

Common Workflows

Accounts

instantly account list --limit 25 --output json
instantly account get --email [e-mail]
instantly account warmup-enable --emails [e-mail],[e-mail]
instantly account warmup-disable --emails [e-mail]
instantly account pause --email [e-mail]
instantly account resume --email [e-mail]
instantly account test-vitals --emails [e-mail]

Notes:

• Account lookup is often email-based rather than ID-based.
• Bulk-style account actions often use comma-separated --emails.

Campaigns

instantly campaign list --limit 50 --output json
instantly campaign get --id <campaign-uuid>
instantly campaign create --name "Q2 Outbound" --schedule '<schedule-json>' --sequences '<sequences-json>'
instantly campaign update --id <campaign-uuid> --name "Renamed Campaign"
instantly campaign activate --id <campaign-uuid>
instantly campaign pause --id <campaign-uuid>
instantly campaign export --id <campaign-uuid>
instantly campaign duplicate --id <campaign-uuid> --name "Campaign Copy"
instantly campaign sending-status --id <campaign-uuid>

Notes:

• campaign create and campaign update commonly require JSON strings.
• Use campaign export or campaign share when a workflow involves reuse or portability.

Leads

instantly lead list --campaign <campaign-uuid> --limit 100 --output json
instantly lead get --id <lead-uuid>
instantly lead create --email [e-mail] --campaign <campaign-uuid>
instantly lead update --id <lead-uuid> --first-name "Casey"
instantly lead bulk-add --campaign-id <campaign-uuid> --file ./leads.json
instantly lead merge --lead-id <lead-uuid> --destination-lead-id <lead-uuid>
instantly lead update-interest --lead-email [e-mail] --interest-value 1 --campaign-id <campaign-uuid>
instantly lead move --campaign <source-campaign-uuid> --to-campaign-id <dest-campaign-uuid> --ids <lead-uuid>

Notes:

• lead list is more filter-heavy than many resources.
• lead bulk-add is the preferred pattern for importing many leads.
• Some lead actions scope by campaign or list rather than only by lead ID.

Emails

instantly email list --limit 20 --output json
instantly email get --id <email-uuid>
instantly email unread-count
instantly email reply --help
instantly email send-test --help

When replying or testing email delivery, inspect help first because these commands often require several content-specific flags.

Webhooks

instantly webhook list --output json
instantly webhook get --id <webhook-uuid>
instantly webhook create --help
instantly webhook update --id <webhook-uuid> --help
instantly webhook-event list --limit 50 --output json
instantly webhook-event summary
instantly webhook-event summary-by-date

Analytics And Deliverability

instantly analytics --help
instantly inbox-placement-test list --output json
instantly inbox-placement-test get --id <test-uuid>
instantly inbox-placement-analytics --help
instantly inbox-placement-report list

These areas are documentation-sensitive. Prefer checking both CLI help and the official docs before issuing a complex analytics command.

Output Expectations

Expect three broad response styles:

1. JSON objects or arrays, especially with --output json
2. Human-readable tables with --output table
3. Plain success lines for certain mutate/toggle/delete commands

If a workflow needs machine-readability, force JSON output.

Failure Handling

If a command fails:

1. Re-run with --verbose
2. Confirm auth and scopes
3. Confirm the resource/action exists in CLI help
4. Confirm the flag names and JSON shape
5. Check the official docs for the live API semantics

Typical failure sources:

• Missing or wrong API key
• API key missing required scopes
• Invalid resource IDs or account emails
• Bad JSON in flags like --schedule, --sequences, or --json
• Using a feature the installed CLI does not expose
• Rate limiting

Agent Operating Rules

1. Prefer --output json unless the user clearly wants tables.
2. Inspect help before using unfamiliar actions.
3. Do not assume a resource is ID-based; account workflows often use --email.
4. Do not invent JSON shapes for complex flags.
5. Use --all carefully on large workspaces.
6. When a command is absent from help, say the installed CLI does not currently support it.

Minimal Workflow Template

For most tasks, use this sequence:

instantly --help
instantly <resource> --help
instantly <resource> <action> --help
instantly <resource> <action> ... --output json

That is the default safe path for agents using the instantly CLI.