@signaliz/cli

Command-line interface for Signaliz — build campaigns, install MCP, manage API keys.

Current CLI surfaces include GTM Kernel campaign planning/status commands, provider routing for Nango-managed customer API destinations, MCP/Ops observability, enrichment primitives, and live email verification at 0.02 fresh enrichment credits when a new verification is needed.

Monthly plans include unlimited cache search, Campaign Builder, API, MCP, CLI, Ops, and integrations. Team is the $499/month public plan and adds unlimited live Find People and Find Companies in Signaliz; Agency stays $999/month with higher credits and throughput. Fresh credits are used only when Signaliz creates, verifies, or fetches new premium data.

Fresh enrichment throughput now allows Free 60/min, Builder 300/min, Team 600/min, Agency 1,000/min, and Pay-As-You-Go 1,000/min, with a 5,000/hour workspace safety cap.

Where To Start

If you are not sure whether to use the UI, CLI, Codex, MCP, or SDK, start here:

signaliz start

Signaliz is the GTM brain over any stack. Use CLI, MCP, Codex, or SDK when an agent needs to build, audit, route, or debug work. Use the UI as the human cockpit to inspect state, connect tools, approve gated actions, and monitor results.

signaliz start is read-only. It checks workspace health, credits, Ops proof, Kernel readiness, and provider-route blockers, then recommends one next safest move plus exact commands for five plain workflows:

• Build a campaign plan: signaliz build "campaign brief".
• Connect tools and provider routes: signaliz connect.
• Audit previous campaigns: signaliz audit.
• Improve results from learning: signaliz improve <campaign_id>.
• Prove Ops delivery: signaliz prove.

Concepts

Signaliz is the GTM brain over your stack. Six nouns explain the rest:

• Op - one executable unit of work, created from a goal or plan. You run it, poll it, and retrieve results.
• Routine - an Op on a schedule. Each scheduled execution is a Tick, and each Tick produces items you can inspect.
• Sink - a delivery destination such as webhook, CSV, Slack, Sheets, Airbyte, or Nango.
• Kernel - your workspace's persistent GTM state: campaigns, memory, connections, provider routes, and readiness gates.
• Brain - the learning layer over the Kernel. It extracts campaign patterns, calibrates deliverability, and seeds safer defaults.
• Campaign - a governed outbound object built from Kernel state and Brain learning. A Campaign Build is one execution that produces rows and artifacts.

Use Campaign Builder when you need a list now. Use the GTM Kernel when the campaign should persist, route through specific providers, and improve from feedback. Use Ops when the job is prompt-first or recurring, such as monitors, alerts, and ad-hoc pulls.

Install

npm install -g @signaliz/cli

Quick Start

The golden path, in order. Each step shows the canonical command surface; compatibility aliases still work, but the README keeps one path visible.

# 1. Authenticate
signaliz auth login

# 2. Orient. This is read-only and prints one next safest move.
signaliz start

# 3. Plan something. Pick the surface that matches the job.
signaliz campaign-agent kit --strategy-template non-medical-home-care --target-count 250 --use-local-leads --json
signaliz campaign-agent memory-kit --strategy-template non-medical-home-care --target-count 250 --use-local-leads --source agency --json
signaliz campaign build --prompt "VP Sales at B2B SaaS, 50-500 employees" --target-count 100 --dry-run
signaliz gtm plan "VP Sales at B2B SaaS, 50-500 employees" --target-count 100 --json > plan.json
signaliz ops plan "Build 100 verified VP Sales leads at B2B SaaS companies"

# 4. Launch only after review.
signaliz campaign build --prompt "VP Sales at B2B SaaS, 50-500 employees" --target-count 100 --confirm-spend --wait
signaliz gtm commit-plan --plan-file plan.json --confirm
signaliz ops create "Build 100 verified VP Sales leads at B2B SaaS companies" --confirm-spend
signaliz ops run <op_id>

# 5. Check status and pull results.
signaliz campaign status <campaign_build_id>
signaliz campaign rows <campaign_build_id> --limit 100
signaliz ops status <op_id>
signaliz ops results <op_id> --limit 100 --json

# 6. Debug async execution when something stalls.
signaliz ops run-status <trigger_run_id> --watch
signaliz ops queue --summary
signaliz ops logs <trigger_run_id>
signaliz ops doctor

Two gates protect you. --confirm-spend approves spendful launches and delivery risk after reviewing an estimate. --confirm writes Kernel or provider-route state after a dry-run. Read-only planning and dry-runs do not spend credits or mutate state.

Authentication

# Interactive login (saves to ~/.signaliz/config.json)
signaliz auth login

# Or set key directly
signaliz auth set-key sk_live_...

# Or use environment variable
export SIGNALIZ_API_KEY=sk_live_...

# Save the active workspace context for deploy/API-key/Ops maintenance commands
signaliz auth workspace set <workspace_id>
signaliz auth workspace show
signaliz auth workspace clear

# Check who you are
signaliz whoami

# Workspace + MCP platform health
signaliz health
signaliz health --json

Discovery

# List all MCP tools
signaliz tools
signaliz tools --json

# Filter by category
signaliz tools --category ops

# Find the right tool/capability by intent
signaliz discover --query "verify a batch of emails"
signaliz discover --query "create an output sink and attach it to a routine" --category ops

Human discovery output includes safety metadata from the MCP registry: permission level, destructive/idempotent/retryable hints, contract version, rate-limit key, and required auth scopes. Use --json when agents need the full structured metadata.

Quickstart/template output also shows primitive IDs and primitive graph policy metadata when the backend returns it, so operators can inspect retry, concurrency, and rate-limit behavior before running an Op.

Custom AI Enrichment - Multi Model

Run custom AI enrichment with the Signaliz-hosted default model. The response includes model readback metadata so callers can audit which model ran.

signaliz ai multi-model \
  --prompt "Research {{company_name}} and score ICP fit for enterprise sales." \
  --input-json '{"company_name":"Stripe","company_domain":"stripe.com"}' \
  --output-fields fit_score:number,reasoning:text \
  --confirm-spend

signaliz ai multi-model \
  --prompt "Review this PDF and extract buyer pains for {{company_name}}." \
  --records-file accounts.json \
  --attachment-fields pdf_url \
  --output-fields pains:array,next_step:text \
  --confirm-spend

Lead Generation And Email

# Preview spend approval requirements. This returns APPROVAL_REQUIRED.
signaliz lead generate \
  --prompt "VP Sales at B2B SaaS companies, 50-500 employees" \
  --max-leads 100

# Launch after reviewing estimated credits
signaliz lead generate \
  --prompt "VP Sales at B2B SaaS companies, 50-500 employees" \
  --max-leads 100 \
  --confirm-spend

# Local-business lead generation
signaliz lead local \
  --prompt "dentists in Phoenix, AZ" \
  --target-verified 50 \
  --confirm-spend

# Poll async lead jobs
signaliz lead status <job_id>

# Verify or find emails. `email find` uses the V3 waterfall:
# primary discovery, secondary enrichment, verified guesses, then paid fallback if needed.
signaliz email verify [email protected]
signaliz email verify-batch --emails [email protected],[email protected]
signaliz email status <job_id>
signaliz email find --company-domain stripe.com --full-name "Jane Smith"

GTM Kernel

Use this path when the campaign should become durable workspace state. The plan is read-only, commit-plan dry-runs first, and writes require --confirm.

# Inspect the workspace Kernel context available to agents
signaliz gtm context
signaliz gtm context --no-memory --limit 5 --json

# Check Kernel, Brain, feedback, memory, and connection readiness gates
signaliz gtm bootstrap
signaliz gtm bootstrap --campaign-id <campaign_id> --include-samples --json

# Compose a read-only campaign build plan before creating, routing, or spending
signaliz gtm plan "Find CTOs at fintech startups in NYC" \
  --target-count 100 \
  --layers icp,lead_generation,email_verification,sender,feedback \
  --preferred-providers instantly \
  --include-planned

# Save the JSON plan, then dry-run a reviewed campaign-object commit
signaliz gtm plan "Find CTOs at fintech startups in NYC" --target-count 100 --json > plan.json
signaliz gtm commit-plan --plan-file plan.json
signaliz gtm commit-plan --plan-file plan.json --confirm

# List and inspect first-class GTM campaigns
signaliz gtm campaigns --status active
signaliz gtm campaign <campaign_id> --log-limit 20 --memory-limit 20

# Search ranked GTM memory instead of dumping raw history
signaliz gtm memory "positive replies from technical founders" \
  --outcome-type positive_reply \
  --limit 10

# Plan Brain learning in dry-run mode
signaliz gtm learning <campaign_id> --include-network --write-mode dry_run
signaliz gtm learning-run <campaign_id> \
  --phases workspace_pattern_extraction,failure_pattern_detection,defaults_seed,delivery_risk \
  --write-mode dry_run
signaliz gtm calibrate <campaign_id> --min-sample-size 10

# Inspect and repair provider readiness without leaving the CLI
signaliz gtm execution <campaign_id>
signaliz gtm integrations --campaign-id <campaign_id> --include-planned
signaliz gtm nango connect \
  --provider-id apollo \
  --integration-id apollo
signaliz gtm nango tools \
  --workspace-connection-id <workspace_connection_id> \
  --provider-config-key apollo
signaliz gtm route-preview --campaign-id <campaign_id> --layer sender
signaliz gtm activate-route --campaign-id <campaign_id> \
  --provider-id instantly \
  --layer sender

# Derive exact dry-run build input from the committed GTM campaign object
signaliz gtm prepare-build <campaign_id> --build-input --json > build-args.json
signaliz campaign build --input-file build-args.json --confirm-spend

# Write route changes only after reviewing the dry-run
signaliz gtm activate-route --campaign-id <campaign_id> \
  --provider-id instantly \
  --layer sender \
  --confirm

# Prepare feedback ingress with feedback-triggered Brain learning
signaliz gtm feedback-webhook --provider instantly \
  --campaign-id <campaign_id> \
  --write-mode dry_run

Campaign Builder

Strategy-template campaign agent

Use gtm strategy-memory to verify that private-safe strategy/workflow memory is seeded before asking the campaign agent to plan:

signaliz gtm strategy-memory \
  --strategy-template non-medical-home-care \
  --include-samples \
  --json

Use gtm agent-template when you want the hosted MCP surface to emit reusable CampaignBuilderAgentRequest JSON before planning:

signaliz gtm agent-template \
  --goal "Build a strategy-template campaign for mature local operators" \
  --strategy-template non-medical-home-care \
  --target-count 250 \
  --use-local-leads \
  --with-byo-placeholder \
  --json

Use gtm agent-plan when you want the CLI to call the hosted MCP campaign-agent planner directly:

signaliz gtm agent-plan \
  --goal "Build a strategy-template campaign for mature local operators" \
  --strategy-template non-medical-home-care \
  --target-count 500 \
  --builtins lead_generation,local_leads,email_finding,email_verification,signals \
  --custom-tool workspace_mcp:enrichment:account_enrich:workspace-mcp \
  --json

Use campaign-agent when you want the CLI to assemble the full MCP plan first: private-safe strategy template, strategy-memory readiness, Brain risk, built-in Signaliz lanes, and BYO tool routes. BYO routes include read-only gtm_provider_recipe_prepare and gtm_provider_route_activate dry-run steps before any custom provider tool can run. Planning and dry-runs are read-only/spend-safe; launches require explicit approval flags.

signaliz campaign-agent init \
  --strategy-template non-medical-home-care \
  --target-count 250 \
  --use-local-leads \
  --with-byo-placeholder \
  --output-file campaign-request.json

signaliz campaign-agent memory-kit \
  --strategy-template non-medical-home-care \
  --target-count 250 \
  --use-local-leads \
  --source agency \
  --json

signaliz campaign-agent plan \
  --goal "Build a strategy-template campaign for mature local operators" \
  --strategy-template non-medical-home-care \
  --target-count 500 \
  --builtins lead_generation,local_leads,email_finding,email_verification,signals \
  --custom-tool workspace_mcp:enrichment:workspace_enrich:workspace-mcp \
  --json

signaliz campaign-agent plan \
  --request-file campaign-request.json \
  --target-count 250 \
  --json

signaliz campaign-agent dry-run \
  --goal "Build a strategy-template campaign for mature local operators" \
  --target-count 500 \
  --json

signaliz campaign-agent build-approved \
  --goal "Build a strategy-template campaign for mature local operators" \
  --confirm-launch \
  --approve-all \
  --approved-by [email protected] \
  --spend-limit 500 \
  --json

Build a campaign

# Minimal — just a prompt
signaliz campaign build --prompt "Find CTOs at fintech startups in NYC"

# Full options
signaliz campaign build \
  --prompt "VP Engineering at Series B+ companies" \
  --target-count 5000 \
  --confirm-spend \
  --outputs csv \
  --industries "SaaS,Fintech" \
  --geographies "US,UK" \
  --wait \
  --json

# With webhook delivery
signaliz campaign build \
  --prompt "Sales Directors at healthcare companies" \
  --target-count 200 \
  --confirm-spend \
  --webhook-url https://hooks.example.com/leads \
  --hmac-secret-ref WEBHOOK_SECRET

# Validate and inspect the plan before launching spendful work
signaliz campaign build \
  --prompt "CTOs at fintech startups in NYC" \
  --target-count 10000 \
  --dry-run \
  --allow-downscale \
  --json

# Approve a pending webhook delivery
signaliz campaign approve <campaign_build_id> \
  --destination-type webhook \
  --webhook-url https://hooks.example.com/leads

# From a JSON config file
signaliz campaign build --input-file campaign.json --wait

Check status

signaliz campaign status <campaign_build_id>
signaliz campaign status <campaign_build_id> --json

Retrieve rows

# First page (50 rows default)
signaliz campaign rows <campaign_build_id>

# Custom page size
signaliz campaign rows <campaign_build_id> --limit 200

# Paginate with cursor
signaliz campaign rows <campaign_build_id> --limit 100 --cursor <next_cursor>

# Dump all rows (caution: large datasets)
signaliz campaign rows <campaign_build_id> --all --json

# Filter by segment
signaliz campaign rows <campaign_build_id> --segment signal

# Filter by qualification or row status
signaliz campaign rows <campaign_build_id> --qualified
signaliz campaign rows <campaign_build_id> --row-status succeeded

List artifacts

signaliz campaign artifacts <campaign_build_id>
signaliz campaign artifacts <campaign_build_id> --json

Cancel a build

signaliz campaign cancel <campaign_build_id>
signaliz campaign cancel <campaign_build_id> --reason "Wrong ICP"

MCP Server Installation

Install the Signaliz MCP server for your AI agent:

# Claude Code
signaliz mcp install --agent claude-code

# OpenAI Codex
signaliz mcp install --agent codex

# Manus
signaliz mcp install --agent manus

# Generic (prints config JSON to stdout)
signaliz mcp install --agent generic

Installed agents can call Signaliz MCP tools for GTM Kernel reads, Campaign Builder execution, Nango-aware provider route activation, and the 100-record email verification primitive.

Ops Execution And Observability

Prompt-first Ops stay simple for beginners, but the CLI exposes production inspection paths for operators debugging asynchronous workflows. The canonical surface is signaliz ops ...; shortcut aliases remain available for existing scripts but are not needed for new work.

# Natural-language planning and creation
signaliz ops autopilot
signaliz ops plan "Monitor these accounts daily and alert Slack on funding signals"
# Human plan output includes run-now, schedule, approval, status, results, and Nango dry-run gates.
signaliz ops create "Monitor strategic accounts and alert Slack on funding or CRM updates" \
  --cadence daily \
  --timezone America/Phoenix \
  --wake-on-events company_funded,crm.updated \
  --activate \
  --confirm-spend
signaliz ops schedule "Monitor strategic accounts and alert Slack on funding or CRM updates" \
  --timezone America/Phoenix \
  --wake-on-events company_funded,crm.updated \
  --destinations slack \
  --confirm-spend \
  --wait \
  --limit 100 \
  --json
signaliz ops quickstart company_research
signaliz ops create "Build 100 verified VP Sales leads at B2B SaaS companies" --confirm-spend

# Bring any customer-owned API into Ops through Nango
signaliz ops nango search hubspot --intent ops --action-name upsert-contact --required-fields email,company --json
signaliz ops nango tools --workspace-connection-id <workspace_connection_id> --json
signaliz ops nango call <action_name> --workspace-connection-id <workspace_connection_id> --input-json '{"rows":[]}' --dry-run --json
# --wait uses the native nango_mcp_tool_call_and_wait tool for a single execute-and-result packet
signaliz ops nango call <action_name> --workspace-connection-id <workspace_connection_id> --input-json '{"rows":[]}' --execute --confirm --wait --json
# schedule/recur uses native ops_nango_schedule(_and_wait) instead of a generic destinations payload
signaliz ops nango schedule "Monitor accounts daily and upsert approved rows to HubSpot" --workspace-connection-id <workspace_connection_id> --provider-config-key hubspot --action-name upsert-contact --input-json '{"source":"signaliz"}' --required-fields email,company --confirm-spend --write-confirmed --wait --json
signaliz ops execute "Build 50 approved ICP leads and upsert them to HubSpot" \
  --destinations nango \
  --workspace-connection-id <workspace_connection_id> \
  --provider-config-key hubspot \
  --action-name upsert-contact \
  --dry-run

# Execute and inspect Op-level results
signaliz ops execute "Build 50 approved ICP leads and return reviewed rows" \
  --confirm-spend \
  --wait \
  --limit 50 \
  --json
signaliz ops run <op_id>
signaliz ops run <op_id> --wait --limit 100 --json
signaliz ops wait <op_id> --limit 100 --json
signaliz ops status <op_id>
signaliz ops results <op_id> --limit 100 --json
signaliz ops results <op_id> --include-failed-runs --json

# Save repeatable local Ops command recipes
signaliz ops saved save daily-goal -- create "Build 100 verified VP Sales leads" --target-count 100
signaliz ops saved save daily-monitor -- plan "Monitor key accounts daily" --cadence daily --destinations slack,csv
signaliz ops saved list
signaliz ops saved run daily-monitor --json
signaliz ops saved delete daily-monitor

# Inspect Trigger.dev execution state
signaliz ops run-status <trigger_run_id>
signaliz ops run-status <trigger_run_id> --watch --interval-ms 5000 --max-polls 60
signaliz ops run-status --run-ids run_a,run_b --json

# Inspect async queue depth, provider pressure, and individual jobs
signaliz ops queue
signaliz ops queue --summary
signaliz ops queue --job-id <api_request_queue_id>
signaliz ops queue --idempotency-key <key>

# Stream live run logs
signaliz ops logs <trigger_run_id>
signaliz ops logs <trigger_run_id> --since <event_id> --filter error

# Replay a failed execution from a captured checkpoint
signaliz ops replay <execution_event_id>

# Approve or reject pending Ops approval tokens
signaliz ops approve <approval_token_id> --decision approved
signaliz ops approve --token-ids token_a,token_b --decision rejected --notes "Needs review"

# Inspect and manually run routines
signaliz ops routines --status active
signaliz ops routine <routine_id>
signaliz ops routine <routine_id> run --force
signaliz ops routine <routine_id> ticks --limit 20
signaliz ops routine <routine_id> items --state failed --json

# Pull operator telemetry from the Ops dashboard API
signaliz ops dashboard summary
signaliz ops dashboard functions --time-range-days 7 --json
signaliz ops dashboard recent --limit 25
signaliz ops dashboard timeseries --granularity hour --json

Machine-Readable Output

All commands support --json for structured JSON output using the standard MCP response envelope:

signaliz campaign build --prompt "..." --json
signaliz campaign build --prompt "..." --wait --json
signaliz campaign status <id> --json
signaliz campaign rows <id> --limit 100 --json
signaliz whoami --json
signaliz health --json
signaliz tools --json
signaliz discover --query "verify emails" --json
signaliz lead status <job_id> --json
signaliz email verify [email protected] --json
signaliz ops queue --summary --json
signaliz ops run-status <trigger_run_id> --json
signaliz ops replay <execution_event_id> --json
signaliz ops dashboard summary --json

When campaign build --wait --json is used, the CLI emits one valid JSON document with both initial and final states.

Environment Variables

| Variable | Description | |---|---| | SIGNALIZ_API_KEY | API key (overrides saved config) | | SIGNALIZ_API_URL | Override base URL. Both https://api.signaliz.com and https://api.signaliz.com/functions/v1 are accepted. | | SIGNALIZ_WORKSPACE_ID | Workspace UUID for keys/deploy |

Config File

The CLI stores configuration in ~/.signaliz/config.json (mode 0600). The file contains your API key, optional workspace context created by signaliz auth workspace set, and local saved Ops command recipes created by signaliz ops saved save. SIGNALIZ_API_KEY and SIGNALIZ_WORKSPACE_ID override saved config values for one-off execution.