Salesforge CLI - Run your outbound stack from the terminal

What is the Forge CLI?

The Forge CLI is a command line tool that lets you run your entire Salesforge stack from your terminal.

Once installed, you can do everything you would normally do in the dashboards by typing a single command.

This includes:

• Creating and managing workspaces

• Building and updating sequences

• Managing contacts and leads

• Searching and enriching new leads

• Managing domains and mailboxes

• Checking warmup stats and placement tests

• Pulling reporting data into your own scripts

Instead of clicking through the UI, you can run, automate and chain product actions directly from your shell.

Why this matters

Most outbound teams have parts of their workflow that they repeat every day or every week. Creating workspaces, refreshing lead lists, rotating mailboxes, exporting performance data.

The Forge CLI removes the manual steps.

You can:

• Script repeatable tasks once and run them on a schedule

• Plug Salesforge data into your existing tooling and dashboards

• Trigger bulk actions across multiple workspaces in seconds

• Hand off operational work to engineers without giving them dashboard access

It is the same engine the dashboards use, just exposed as commands.

How the CLI works

The CLI talks directly to each product's API using your API keys. Keys stay on your machine and are stored in a local config file with restricted permissions.

Key points:

• Your API keys stay on your computer

• Each command only needs the key for the product it touches

• All actions are executed through authenticated API requests

You can also run the CLI in MCP mode, which lets AI assistants like Claude, Cursor and Windsurf use the same commands as tools. More on that below.

Supported Products

The CLI supports the full Forge suite through a single binary:

• Salesforge - Workspaces, contacts, sequences, mailboxes, sender profiles, enrollments, webhooks, email validation, do-not-contact lists

• Primeforge - Workspaces, domains, mailboxes, DNS management, prewarmed mailboxes

• Leadsforge - Contact search, email/phone/LinkedIn enrichment, lookalike search

• Infraforge - Workspaces, domains, mailboxes, DNS, domain availability, credits

• Warmforge - Mailboxes, warmup stats, placement tests

• Mailforge - Workspaces, domains, mailboxes, DNS, domain availability

You only need API keys for the products you actually use. Commands for products without a configured key will return an authentication error.

Step by Step Guide to set up the CLI

Prerequisites

• An account on one or more Salesforge products with API access

• Node.js version 20.11 or newer installed on your machine

• A terminal (Terminal on macOS, PowerShell or Windows Terminal on Windows)

Step 1: Install the CLI

Run this in your terminal:

npm install -g @salesforge/forge-cli

After install, check that it works:

forge --help

Step 2: Get your API keys

Generate API keys for each product you want to use:

• Salesforge: Log in at app.salesforge.ai, go to Settings > API, click Generate API Key

• Primeforge: Log in at app.primeforge.ai, go to Settings > API, click Generate API Key

• Leadsforge: Log in at app.leadsforge.ai, go to Settings > API, click Generate API Key

• Infraforge: Log in at app.infraforge.ai, go to Settings > API, click Generate API Key

• Warmforge: Log in at app.warmforge.ai, go to Settings > API, click Generate API Key

• Mailforge: Log in at app.mailforge.ai, go to Settings > API, click Generate API Key

Copy each key and keep it somewhere safe. You will need them in the next step.

Step 3: Log in

The recommended way is to pass the key through stdin so it never ends up in your shell history:

printf '%s' "$SALESFORGE_API_KEY" | forge login salesforge --key-stdin
printf '%s' "$MAILFORGE_API_KEY" | forge login mailforge --key-stdin

Repeat for each product you want to connect.

You can also export environment variables instead, which is the right choice for CI and automation:

export SALESFORGE_API_KEY="..."
export PRIMEFORGE_API_KEY="..."
export LEADSFORGE_API_KEY="..."
export INFRAFORGE_API_KEY="..."
export WARMFORGE_API_KEY="..."
export MAILFORGE_API_KEY="..."

To check which products are configured:

forge status --pretty

Stored config lives at ~/.config/forge-cli/config.json and is written with file mode 0600. If you manage multiple accounts, use the --profile flag.

Step 4: Run your first command

List your Salesforge workspaces:

forge salesforge workspaces list --limit 50 --pretty

Get a single workspace:

forge salesforge workspaces get --workspace-id ws_123

List active Mailforge domains:

forge mailforge domains list --status active

That is it - you are running Forge from the terminal.

Discovering commands

The CLI has a built in command browser, so you do not need to memorise anything.

# Show every command available with the keys you currently have configured
forge commands list --available --names

# Show every command across all products
forge commands list --pretty

# Filter to one product
forge commands list --product mailforge --names

# Get details and inputs for a specific command
forge commands describe mailforge_list_domains --pretty

# Or use the --help flag on any command
forge mailforge domains list --help

Commands can be called in two forms:

• Grouped form - readable, great for humans: forge salesforge workspaces list

• Registry name form - flat names, great for scripts: forge list_workspaces

Flags use kebab-case and are mapped to the underlying API field names, so --workspace-id becomes workspaceId automatically.

Passing complex inputs

For commands that accept nested objects, you can use JSON, a file, or stdin:

# Inline JSON
forge leadsforge_search --json '{"limit":10,"leadLocations":{"include":["United States"]}}'

# From a file
forge create_contact --file contact.json

# Piped from another command
cat search.json | forge leadsforge_search --stdin

Output formats

By default the CLI prints compact JSON to stdout, which is ideal for piping into jq, scripts, or other tools.

# Compact JSON, default
forge salesforge workspaces list

# Pretty-printed for reading
forge salesforge workspaces list --pretty

# Only the fields you care about
forge mailforge domains list --fields id,name,status

# Suppress output for create or update commands
forge salesforge workspaces create --name "Outbound" --quiet

Errors are JSON written to stderr, which makes them easy to detect in scripts:

{"error":"Salesforge API key is required","code":"AUTH_ERROR"}

Exit codes follow standard conventions:

• 0 - Success

• 1 - Runtime, network, API, or command error

• 2 - Usage error

• 3 - Authentication or configuration error

Using the CLI with AI assistants

The same binary can also run as an MCP server, which lets Claude, Cursor, Windsurf and other MCP-compatible AI assistants use Forge commands as tools.

Add this to your AI assistant's MCP config:

{
  "mcpServers": {
    "forge": {
      "command": "forge",
      "args": ["mcp"],
      "env": {
        "SALESFORGE_API_KEY": "...",
        "MAILFORGE_API_KEY": "..."
      }
    }
  }
}

Only configure the keys for products you actually use. Tools for unconfigured products will not appear.

If you want a hosted alternative that does not require installing the CLI, see our separate guide on the Forge MCP Server.

Common workflows

A few examples of what teams typically automate first:

• Daily lead refresh - Use Leadsforge to pull a fresh list of contacts that match your ICP, then push them straight into a Salesforge sequence

• Mailbox health check - Pull warmup stats and placement test results from Warmforge each morning and post a summary to Slack

• Domain rotation - List Mailforge or Infraforge domains and mailboxes, identify any that are unhealthy, and reassign senders

• Bulk workspace setup - Create a workspace, add senders, import contacts, and start a sequence in one script for new clients

Anything that takes more than a few clicks in the dashboard is a good candidate.

Troubleshooting

forge: command not found - Make sure your global npm bin directory is on your PATH. Run npm bin -g to see the path.

Salesforge API key is required - Either log in for that product (forge login salesforge --key-stdin) or export the matching environment variable.

Wrong key being used - Per-command flags override environment variables, which override stored config. Use forge status --pretty to see what is currently active.

Need a different account - Use --profile <name> to keep multiple sets of credentials side by side, or --config <path> to point at a different config file.

Resources

• npm package: https://www.npmjs.com/package/@salesforge/forge-cli

• GitHub repo: https://github.com/SalesforgeAI/forge-cli

If you run into issues, reach out via the support chat and we will help you get unblocked.