@signaliz/cli

The Signaliz CLI exposes all five core products, Signal Awareness, Signaliz Flow, and delivered managed builds through one public contract:

npm install -g @signaliz/cli
signaliz auth login

# Production REST gateway:
# https://api.signaliz.com/functions/v1/api/v1/find-email
# https://api.signaliz.com/functions/v1/api/v1/verify-email
# https://api.signaliz.com/functions/v1/company-signal-enrichment-v2
# https://api.signaliz.com/functions/v1/api/v1/signal-to-copy
# https://api.signaliz.com/functions/v1/api/v1/signals-first
# /api/v1/signals remains a compatibility alias.
# https://api.signaliz.com/functions/v1/api/v1/signal-awareness/signals
# https://api.signaliz.com/functions/v1/api/v1/signal-awareness/companies/add
# https://api.signaliz.com/functions/v1/api/v1/signal-awareness/companies/delete
# https://api.signaliz.com/functions/v1/api/v1/signal-awareness/companies/schedule
# https://api.signaliz.com/functions/v1/api/v1/flow
# https://api.signaliz.com/functions/v1/api/v1/managed-builds
# The same contracts are available under /api/v2/.

signaliz find-email --company-domain example.com --full-name "Jane Doe"
# An HTTPS LinkedIn person profile URL (/in/<slug>) is sufficient without a name or company domain
signaliz find-email --linkedin-url "https://www.linkedin.com/in/jane-doe"
signaliz verify-email [email protected]
# Preview any single or batch product request without provider calls or credits
signaliz verify-email [email protected] --dry-run --json
# Return early when a provider check runs long, then resume the exact run
signaliz verify-email [email protected] --no-wait --json
signaliz verify-email --verification-run-id run_... --json
signaliz company-signals --domain example.com \
  --research-prompt "Find recent signals that explain why this company would use Signaliz."
signaliz signal-to-copy \
  --company-domain example.com \
  --person-name "Jane Doe" \
  --title "VP Sales" \
  --campaign-offer "pipeline intelligence" \
  --run-without-signal no

# Reuse the exact Signals First snapshot, fact, or event instead of rediscovering it.
# Keep company/recipient/offer fields so Signaliz can validate identity and write the copy.
signaliz signal-to-copy --fact-id <64-character-sha256> \
  --company-domain example.com --person-name "Jane Doe" \
  --title "VP Sales" --campaign-offer "pipeline intelligence"

# Opt into slower deep research when needed
signaliz signal-to-copy --company-domain example.com --person-name "Jane Doe" \
  --title "VP Sales" --campaign-offer "pipeline intelligence" --deep-search

# Omit --deep-search for bounded credit-free first-party and Bing grounding.

# Signals First returns cached, source-backed companies first and automatically
# follows the durable run through any bounded live-search top-off.
signaliz signals-first "companies that just got funded" --limit 100
# Automation can return the first receipt immediately and resume it later.
signaliz signals-first "companies that just got funded" --limit 100 --no-wait
signaliz signals-first --signal-search-run-id run_... --json

# Monitor companies with the fixed Company Signal evidence engine.
signaliz awareness add --domain acme.com --schedule daily
signaliz awareness signals --domain acme.com --json
signaliz awareness schedule --domain acme.com --schedule monthly
signaliz awareness delete --domain acme.com

# Flow starts and resumes through the versioned REST contract.
signaliz flow --signal-query "companies with recent hiring" \
  --campaign-offer "pipeline intelligence"
signaliz flow --run-id run_... --json
# Keep polling the returned run ID until status is completed or failed.
# Flow leaves generated copy in review and never sends outreach.

# Delivered GTM Contractor builds publish their Clay budget and fixed
# Signaliz-credit price before each reusable run.
signaliz builds list
signaliz builds get --build-id BLD-A1B2C3D4E5F6
signaliz builds run --build-id BLD-A1B2C3D4E5F6 \
  --input request.json --idempotency-key customer-run-001
signaliz builds status --run-id 11111111-1111-4111-8111-111111111111 --json

Use --json with any product command for structured output.

The four row-oriented products accept a JSON array or JSONL file for scale:

signaliz find-email --input contacts.jsonl --concurrency 20 --json
signaliz verify-email --input emails.json --concurrency 20 --json
signaliz company-signals --input companies.jsonl --concurrency 5 --json
signaliz signal-to-copy --input copy-requests.jsonl --concurrency 5 --json

# Yield an agent turn immediately for a durable >25-row batch.
# The response includes both job_id and the actual idempotency_key.
signaliz company-signals --input companies.jsonl --no-wait --json
signaliz company-signals --job-id job_... --idempotency-key key_... --json
signaliz signal-to-copy --input copy-requests.jsonl --no-wait --json
signaliz signal-to-copy --job-id job_... --idempotency-key key_... --json

Signal to Copy accepts fact_id or event_id in JSON/JSONL rows, and the equivalent --fact-id or --event-id flags for one request. These references reuse canonical evidence in single calls and synchronous batches of at most 25. Durable batches of 26-5,000 reject canonical references instead of silently rediscovering them. JSON output exposes the normalized customer-facing signal fields; human output prints the signal type, verified source URL, date, company name, and domain.

Retrieve completed Company/Copy result pages within seven days. If retention expires, the CLI returns non-retryable BATCH_RESULTS_EXPIRED; do not automatically rerun the submission because provider work may already have been performed.

The CLI compacts exact duplicate successes by default: the first row contains the full result and repeats contain duplicateOf pointing to its zero-based input index. Use --expand-duplicates only when every repeated row must contain the full payload.

For large machine-readable batches, JSONL avoids building one giant output string and --omit-raw removes the duplicated provider response retained by the SDK for diagnostics:

signaliz company-signals --input companies.jsonl --jsonl --omit-raw

# Stream JSONL directly from another process; no temporary file is required.
generate-company-rows | signaliz company-signals --input - --jsonl --omit-raw

JSONL writes one { "type": "result", ... } line per input followed by one { "type": "summary", ... } line. Input order and cardinality are preserved. Failed result lines preserve errorCode, retryEligible, and retryAfterSeconds when the API supplies recovery guidance. The CLI exits non-zero whenever a single result has success: false or a batch contains any failed row. Machine output remains complete, so agents can inspect successful rows while treating the command as failed. Contradictory HTTP 200 payloads also fail closed: ok: false, explicit error fields or arrays, and terminal failure statuses cannot leave send-safe email, signal evidence, or generated copy in the normalized result.

If a single request or batch submission response is lost, rerun the same command with --idempotency-key <key> to recover the original request, durable job, or provider run without duplicate work or spend. The same key is portable across CLI, SDK, REST API, and MCP calls for the same workspace and logical input; chunked batches retain collision-free keys for each original row. Add --dry-run to any product command, including one using --input, to receive a conservative credit ceiling without provider calls, jobs, writes, or spend. JSON plans expose submitted, unique-fresh, and duplicate-suppression counts; human output calls out exact duplicates whenever they reduce the ceiling.

Batch input is capped at 5,000 records, concurrency is bounded to 1-50, input order is preserved, and a failed item does not abort successful items. Synchronous exact duplicates are single-flighted. Durable Company/Copy submissions preserve every row and index so idempotency stays stable across REST, MCP, SDK, and CLI recovery. The four row-oriented core products use one recoverable REST job for inputs larger than 25; the CLI waits by default or returns job_id, idempotency_key, and an exact resume command with --no-wait. Find Email, Verify Email, and Company Signal Enrichment use 25-row pages; Signal to Copy uses 100-row pages. Large Find Email and Verify Email batches honor --max-wait-ms and --poll-interval-ms. Durable Signal to Copy jobs complete missing company-signal research before generating copy and accept uniform --deep-search controls. Company Signal signal_run_id recovery rows likewise stay in direct batches of at most 25. Large Company Signal jobs persist bounded result pages and exclude rejected candidate-evidence diagnostics; use --include-candidate-evidence only with batches of at most 25.

Every command uses the authenticated workspace. Find Email costs 1 credit per returned result and Verify Email costs 0.02 credits per returned terminal result on every plan. Signaliz automatically reuses eligible evidence and prevents duplicate provider work. Builder, Team, Agency, and Pay-As-You-Go include Company Signals. Signal to Copy costs 1 credit per successful result on Free and Builder, and is unlimited on Team and Agency. --lookback-days remains a hard evidence-age bound.

Signals First is a query-first company discovery command rather than a row batch. It returns only dated, source-linked signals that contain both a company name and company domain. The default request is 100 companies and the maximum is 100. It is included on Builder, Team, and Agency plans, is resumable with signal_search_run_id, and reports measured source cost plus target warnings without rejecting a valid run solely on a projected preflight estimate. A request is a ceiling, not a promise: it can return fewer results when public evidence cannot verify both a date and company identity. Use --icp-context to qualify an open-ended signal request against a target market.

Connection commands are limited to access infrastructure:

signaliz auth set-key sk_live_...
signaliz auth workspace set <workspace_id>
signaliz auth status
signaliz health
signaliz tools
signaliz mcp install

Configuration is stored in ~/.signaliz/config.json with file mode 0600. SIGNALIZ_API_KEY, SIGNALIZ_API_URL, and SIGNALIZ_BASE_URL override the saved configuration.

Campaign Memory in Codex or a terminal

Campaign Memory commands use the canonical client-brain API. They reuse your Signaliz API key and workspace configuration; the API rechecks current access on every request. Use exact client and campaign IDs from discovery, so a similar client name cannot select another account.

signaliz auth login
signaliz campaign-memory status --json
signaliz campaign-memory clients --json
signaliz campaign-memory connections --client-id <client-uuid> --json

# Read a provider key from an environment variable already available to your shell.
signaliz campaign-memory connect --client-id <client-uuid> --provider instantly \
  --provider-key-env INSTANTLY_API_KEY --idempotency-key <request-uuid> --json

# Refresh one saved connection, or retry its initial history import.
signaliz campaign-memory sync --client-id <client-uuid> --connection-id <connection-uuid> --json

signaliz campaign-memory campaigns --client-id <client-uuid> --limit 50 --json
signaliz campaign-memory campaign --client-id <client-uuid> --campaign-id <campaign-uuid> --json
signaliz campaign-memory results --client-id <client-uuid> --campaign-id <campaign-uuid>
signaliz campaign-memory ask "What worked, what didn't, and why?" \
  --client-id <client-uuid> --campaign-id <campaign-uuid> --json
signaliz campaign-memory recommend --client-id <client-uuid> --campaign-id <campaign-uuid> --json

# Prepare a proposal, then resume its saved generation without creating another request.
signaliz campaign-memory draft --client-id <client-uuid> \
  --objective "Improve our next campaign using this client's evidence" \
  --idempotency-key next-campaign-001 --no-wait --json
signaliz campaign-memory draft --client-id <client-uuid> --generation-id <generation-uuid> --json
signaliz campaign-memory history --client-id <client-uuid> --json

# Source intake is private by default. Share only the context intended for campaign planning.
signaliz campaign-memory remember --client-id <client-uuid> --title "Client brief" --body-file brief.md
signaliz campaign-memory remember --client-id <client-uuid> --title "Approved shared brief" \
  --body-file shared-brief.md --scope client --json

connect supports instantly, smartlead, and bison. Smartlead requires the exact --account-label and an explicit --attest-account; Email Bison requires --provider-base-url. Use --provider-key-stdin instead of --provider-key-env to pipe a key into the command. Provider secrets are never saved in CLI config or printed. Connection status confirms validation/persistence, not completion of campaign learning. The connect response separately reports whether its initial history import was queued. If queuing fails, the saved connection stays valid and the CLI provides a sync retry command. sync reads history for exactly one saved connection; it does not wait for a queued import to finish. A failed sync exits nonzero. Connecting requires a current workspace owner/admin and the appropriate credential scope. context:read permits reads; context:write permits source intake and draft proposals. Follow the API's exact scope error if an operation is unavailable to the current key.

--workspace-id <uuid> checks the intended workspace against the authenticated credential. It cannot grant access to another workspace. Use campaign-memory status to inspect access and Campaign Memory for companion setup. A key with the wrong workspace or revoked membership fails with a useful error instead of silently switching clients.

campaigns supports --query, --provider, and a --cursor returned as next_cursor; pages contain at most 100 campaigns. campaign reads one exact campaign and its available source evidence. results preserves canonical counts, denominators, metric labels, findings, and evidence limits. ask can use only client context when --campaign-id is omitted. recommend returns changes for review; it does not apply a recommendation to a provider.

draft waits for up to five minutes after the initial request by default. Each request also has a bounded timeout. Use --no-wait to return its saved generation immediately, or --max-wait-ms and --poll-interval-ms to bound the wait. The result includes an exact resume command. After an unconfirmed submission, retry the original idempotency key; an existing saved proposal is returned directly. A failed generation exits nonzero; a completed generation requires its matching saved proposal. history means saved proposals/drafts and their generation states, not a list of sent campaigns. No Campaign Memory command loads leads, activates, sends, or approves paid campaign changes.

--json preserves the canonical response, including evidence text and raw counts. It does not apply the row-product output filter. CLI recovery metadata is under cli; known authentication secrets are redacted if a server echoes them. Human output is a readable projection of the same response. All input/auth/API failures return a nonzero exit code and machine-readable errors with --json.

Campaign OS agent harness

Use the same commands from Codex, Claude Code, Cursor, Devin, Grok, or a shell automation. All context is bounded. Safe Campaign OS work runs autonomously; consequential provider actions remain gated:

signaliz campaign-os clients --status active --json
signaliz campaign-os context --client-id <uuid> --json
signaliz campaign-os provider-runtime --client-id <uuid> --provider clay --json
signaliz campaign-os build --client-id <uuid> --name "Launch intent" \
  --objective "Build an evidence-grounded 500-person campaign" \
  --target-count 500 --agent codex --idempotency-key launch-build-v1 --json
signaliz campaign-os build-status --build-run-id <uuid> --json
signaliz campaign-os audience-draft --client-id <uuid> --name "Launch ICP" \
  --definition-file audience.json --entity-type people \
  --audience-role campaign_segment --source-mode signaliz_owned \
  --idempotency-key launch-audience-v1 --json
signaliz campaign-os materialize-cache-audience --client-id <uuid> \
  --audience-id <uuid> --campaign-id <uuid> --target-count 1000 \
  --max-cohorts-per-call 2 \
  --idempotency-key launch-cache-materialization-v1 --json
signaliz campaign-os audience-preview --client-id <uuid> \
  --audience-id <uuid> --idempotency-key launch-preview-v1 --json
signaliz campaign-os compile --client-id <uuid> --campaign-id <uuid> \
  --providers all --json
signaliz campaign-os alpha-materialize-preflight --client-id <uuid> \
  --campaign-id <uuid> --audience-run-id <uuid> --validation-run-id <uuid> \
  --idempotency-key launch-alpha-materialization-v1 --json
signaliz campaign-os alpha-materialize --materialization-run-id <uuid> \
  --approval-hash sha256:<64-hex> --confirm-spend --json
signaliz campaign-os alpha-materialization-status \
  --materialization-run-id <uuid> --json
signaliz campaign-os request --client-id <uuid> --campaign-id <uuid> \
  --agent devin --action provider_activation --instructions "Prepare for review" \
  --preflight-inputs-file action-preflight.json \
  --idempotency-key launch-activation-request-v1 --json
signaliz campaign-os prepare-preflight --client-id <uuid> \
  --request-id <approved-request-uuid> --json
signaliz campaign-os receipts --client-id <uuid> --json

provider-runtime explains the safe Clay or Instantly route, adapter source, approval boundaries, and receipt semantics without returning credentials or calling the provider. build, audience-draft, materialize-cache-audience, audience-preview, and compile do not need CMM-admin approval and keep providers locked. Cache materialization is capped at 500 members and returns exact zero-provider/Clay usage plus a terminal reconciliation receipt; optional --campaign-id links that run to its campaign lifecycle. request requires a nonblank --idempotency-key and creates only an auditable review request for paid sourcing, provider load, activation, real-time arming, queueing, or sending; it does not execute them. --preflight-inputs-file accepts one JSON object containing only exact, non-secret provider and artifact identifiers. After a Signaliz superadmin approves that proposal, prepare-preflight appends or reads the immutable no-call continuation and reports missing inputs or unavailable adapters.

alpha-materialize-preflight records the exact campaign, Audience run, validation receipt, coverage target, batches, and research ceiling without spend. alpha-materialize requires the returned approval hash and --confirm-spend; it authorizes only that bounded research. It never calls Clay, creates an Audience, loads or activates a provider, queues, or sends.