DM Faster CLI
CLI for DM Faster Agent 2.0. Run the version-pinned package, then authenticate through the focused DM Faster browser approval page.
This source prepares the version-pinned 2.3.0 runtime. Verify the coordinated Product and package release before using these new commands against production.
npx --yes @dmfaster/[email protected] auth login --json
npx --yes @dmfaster/[email protected] auth login --access plan --json
npx --yes @dmfaster/[email protected] auth status --json
npx --yes @dmfaster/[email protected] doctor --json
npx --yes @dmfaster/[email protected] describe companies search
npx --yes @dmfaster/[email protected] analytics summary --scope today --json
npx --yes @dmfaster/[email protected] workspace briefing --json
npx --yes @dmfaster/[email protected] campaigns list --status Running --limit 10 --json
npx --yes @dmfaster/[email protected] campaign copy inspect campaign_123 --json
npx --yes @dmfaster/[email protected] conversations list --filter unread --channel linkedin --limit 25 --json
npx --yes @dmfaster/[email protected] conversation inspect conversation_123 --limit 40 --json
npx --yes @dmfaster/[email protected] replies list campaign_123 --limit 5 --query "Visio" --json
npx --yes @dmfaster/[email protected] company timeline campaign_123 outreach_456 --json
npx --yes @dmfaster/[email protected] companies list refine --input reviewed-refinement.json --json
npx --yes @dmfaster/[email protected] companies fit start --input fit-review.json --json
npx --yes @dmfaster/[email protected] companies fit advance --input fit-run.json --json
npx --yes @dmfaster/[email protected] companies fit results --input fit-page.json --json
npx --yes @dmfaster/[email protected] companies fit proposal --input fit-run.json --json
npx --yes @dmfaster/[email protected] history export campaign_123 > campaign-history.jsonl
npx --yes @dmfaster/[email protected] campaign validate --state campaign-state.json --json
npx --yes @dmfaster/[email protected] audience preview --state campaign-state.json --json > audience-preview.json
# Review the exact count and sample in audience-preview.json before continuing.
npx --yes @dmfaster/[email protected] campaign prepare --state campaign-state.json --reviewed-audience audience-preview.json --idempotency-key prepare-001 --json
npx --yes @dmfaster/[email protected] campaign launch preflight campaign_123 --idempotency-key launch-001 --json
npx --yes @dmfaster/[email protected] campaign launch campaign_123 --idempotency-key launch-001 --authorization-id agent_action_… --json
npx --yes @dmfaster/[email protected] auth logout --json
auth login creates a short-lived PKCE device request, prints a confirmation
code, opens the same request in the user's browser, and polls until the user
approves, denies, or lets it expire. The user must compare the browser and CLI
codes and review the exact workspace, expiry, and permissions. The browser never
receives the issued credential.
Login defaults to the complete full profile. Use --access to grant only the
needed capability set:
| Profile | Capability |
|---|---|
read | inspect workspace, campaigns, sending, replies, and pipeline |
plan | read plus industry lookup, validation, and exact audience preview |
draft | plan plus private list/campaign preparation and approved pause requests |
full | draft plus campaign control, inbox replies, pipeline updates, and follow-up cancellation under the owner's grant and explicit instructions |
The server still checks every exact scope, workspace membership, owner-only rule, and action authorization. An access profile is a credential ceiling, not an action approval.
campaigns list accepts --query, --channel, and --cursor alongside status
and limit. Its result includes an exact filtered total and nextCursor. Keep
the same filters on subsequent pages. If the collection changes during paging,
restart with no cursor; a partial set is never reported as complete.
conversations list accepts inbox filters and a cursor as flags. The
conversation inspect command takes the exact conversation ID and optional
message cursor. Both also accept --input FILE for the complete typed input.
history export CAMPAIGN_ID follows the confirmed-send history cursor and
writes JSON Lines to standard output. It checks every page before writing any
rows, so an API or cursor failure cannot produce a partial export. It defaults
to at most 10,000 rows; use --max for a smaller bound or --cursor to start
from a saved history cursor. history list --input FILE remains the typed,
page-by-page path for larger histories and MCP clients.
Login emits two newline-delimited JSON events on stdout: first
authorization_required, then authenticated after a successful exchange.
Human instructions and warnings go to stderr, so scripts can parse stdout
without scraping prose.
Use auth upgrade --access full when an existing credential needs broader
permissions. The old credential remains stored during browser approval. A denied
or expired request keeps it; after secure storage confirms the replacement, the
CLI revokes the old credential. If old remote revocation fails, the CLI reports
that separately while retaining the new working connection. The final JSON
event includes priorCredentialRevoked so scripts can tell whether cleanup
finished.
Approved credentials are stored in macOS Keychain or Linux Secret Service
(secret-tool). Unsupported credential stores fail closed and never write a
plaintext fallback. auth status verifies the configured credential with the
server. auth logout revokes a stored credential before deleting it locally.
Campaign state files contain the complete latest state returned or confirmed by
the caller. Re-send that state for every validation, audience, or preparation
call; the MCP/API process does not keep a hidden planning session. Preparation
commands create private resources and require stable idempotency keys. They also
require --reviewed-audience with the saved, human-reviewed output from the
matching exact preview. The CLI echoes the server-issued audience identity from
that result unchanged; it never derives a signature from the state file.
Agents should assume the user does not know DM Faster's fields or command names:
translate the user's goal into the complete state, ask only for material missing
facts, and carry validation, exact preview, and private draft preparation in
order. dmfaster --help includes the same quick-start sequence for CLI-only
hosts.
The full connection profile includes campaigns:control. After the owner
grants it once, an explicit instruction such as “launch it” is enough. Call
preflight, then execute immediately when it returns ready, using the returned
authorization ID and the same campaign ID and idempotency key. The authorization
remains short-lived and bound to the exact campaign version.
Older connections keep per-action browser approval. Reconnect once with
dmfaster auth upgrade --access full to enable conversational controls, or follow
the returned approval_required URL for a single action. Only the human operates
connection and action approval pages. If launch returns setup_required, show
setup.setupUrl and repeat setup.resume after the extension reconnects.
--json is accepted anywhere and JSON is the default for every API command.
dmfaster doctor checks the Node runtime, secure-store availability, remote
authentication, workspace identity, granted scopes, and scope-eligible tools.
It prints actions to restore a broken connection without exposing the token.
Scope eligibility does not bypass workspace role, plan, or action checks.
Run dmfaster --help for the complete Agent 2.0 command list, or
dmfaster COMMAND --help for a focused description. dmfaster describe COMMAND
returns the exact input schema, required scopes, and effect without signing in.
Commands that accept --input FILE, --state FILE, --reviewed-audience FILE,
or --file FILE also accept - to read one input from standard input. Keep the
reviewed audience preview as the server-issued result; standard input does not
remove its review requirement. The production
API URL defaults to https://app.dmfaster.com.
The CLI also reads $XDG_CONFIG_HOME/dmfaster/config.json (or
~/.config/dmfaster/config.json):
{
"baseUrl": "https://app.dmfaster.com"
}
Environment variables take precedence. DMFASTER_API_URL overrides the base
URL for local development or self-hosting. DMFASTER_TOKEN remains an explicit
developer credential override and takes precedence over the operating-system
store; the CLI rejects plaintext token fields in the JSON config. Never paste a
DM Faster token into chat or MCP configuration.
Import Instagram usernames
Save a reviewed username collection as a private list:
dmfaster list import --name "Finland Coaches" --file instagram-usernames.csv --json
Use a one-column CSV with an optional username or instagram_username header,
or one username per line. UTF-8 BOM, quoted cells, and CRLF are supported. Up to
1,000 rows and 64 KiB are accepted. Invalid rows reject the whole import. Case
and leading @ are normalized; duplicates are reported and removed. The command
derives a stable retry key from the name and unique usernames; supply a new
--idempotency-key to intentionally create another copy.
The SDK equivalent is client.invoke("list.import", { name, usernames, idempotencyKey }). It requires campaigns:write and owner access, and is available on all plans including Basic. A successful result contains listId, name,
importedCount, inputCount, duplicateCount, created, and replayed.
A changed payload or an edited saved list returns idempotency_conflict.
The list is selectable in the campaign builder; no campaign is created and
nothing is sent. Import validates syntax, not live Instagram account existence.
Existing Instagram lists (1.1.0)
Find a saved list, check the whole audience for an exact username, remove a requested target, and prepare an unstarted campaign through the same contract:
dmfaster lists list --query "Coaches" --json
dmfaster list inspect LIST_ID --username pt.j.jylha --json
dmfaster list target remove LIST_ID --username pt.j.jylha --expected-version INSPECTED_UPDATED_AT --json
dmfaster campaign draft prepare --input draft.json --json
Draft JSON contains listId, expectedListUpdatedAt, expectedTargetCount,
name, messageVariants (1–4 strings), dailyCap, pacingSeconds,
onlyNewChats, skipPreviouslyMessaged, and idempotencyKey. Use the version
and exact total from the latest inspection/removal. Preparation verifies the
saved copy and settings and always returns a disabled Draft. It does not
start or arm sending. Reusing a key with different settings or an edited audience
fails without changing the original campaign.
SDK operation names are lists.list, list.inspect, list.target.remove,
campaign.draft.prepare, and campaign.draft.update; MCP names replace dots with underscores. List
reads require campaigns:read; removal requires owner campaigns:write;
draft preparation requires both scopes. No company-search entitlement is needed
for these Instagram lists. Existing campaign launch/pause approval is unchanged.
Instagram campaigns always exclude known contacts: onlyNewChats and
skipPreviouslyMessaged must both be true. Unsupported values are rejected
before a draft is created.
To change an existing disabled, unstarted social campaign draft, use
dmfaster campaign draft update --input update.json --json. Supply campaignId,
expectedCampaignUpdatedAt from campaign inspection, and a nonempty updates
object containing any supported setting: social channel toggles, LinkedIn invite
mode and note, follow-up sequences, description, name, messageVariants,
dailyCap (1–60), pacingSeconds (12–3,600), or sending-window fields.
Omitted settings and the audience are preserved.
Stale versions and started campaigns are rejected. After an uncertain
response, inspect the campaign before retrying. No launch approval is needed to
edit a disabled draft.
For a mixed Instagram/Facebook/LinkedIn draft, use
campaign copy inspect CAMPAIGN_ID --json to read the exact invite mode, note,
saved sequences, Instagram/Facebook messageVariants, and effective
linkedinAcceptedMessage.
To send an invitation without a note and then a DM, set linkedinInviteMode to
invite_only and linkedinFollowUpSequence to an enabled sequence with a first
LinkedIn step containing the DM text. That first step is queued as soon as the
connection is accepted, or immediately if the person is already connected;
its required delayDays: 1 does not delay the acceptance message. Later steps
use their configured delay. A known human reply on another campaign channel
stops unsent LinkedIn steps, with a final check before sending. A LinkedIn-only
campaign uses followUpSequence for these steps. Inspect after updating to
verify the saved copy; editing never launches the draft.
Automatic sending windows are also editable through campaign.draft.update:
instagramSendingWindowEnabled is a boolean; instagramSendingWindowStartMinute
is 0–1380; instagramSendingWindowEndMinute is 60–1440; and
instagramSendingWindowWeekdays is a bitmask from 1–127 (Monday=1, Tuesday=2,
through Sunday=64; Monday–Friday=31). The interval must span at least 60 minutes
in the same day. Times use the workspace timezone returned by campaign.inspect
in settings, alongside the current window, copy, pacing, and enabled state.
Send both endpoints when changing the interval. A saved window can be toggled
on or off while the draft stays disabled; only the separate launch operation
arms the schedule. Started campaigns cannot be edited with this draft tool.
Inspect an ongoing campaign with campaign delivery inspect --input FILE.
Update cap, pace, or sending hours with campaign delivery update --input FILE,
including the inspection revision and an idempotency key. This preserves the run
and audience. Launch and pause return an operation reference; use
campaign operation inspect --input FILE --wait 30 to wait up to 30 seconds for
its receipt. Pending operations can be inspected again with the same IDs.
Browser acknowledgment and confirmed delivery are separate facts.
Saved company contact details
Company search supports the current Companies app filters, including
technologies: ["shopify"] together with metaAdsActiveOnly: true. Discover
country-specific options first, then inspect the returned company identities
before preparing a private shortlist.
Saved company lists preserve available real email, LinkedIn, phone, Instagram,
and Facebook routes. Names and roles stay with the selected contact for each
channel; inspect the full company profile for all decision-makers. Generated
company.… identities are never Instagram targets, and contactless companies
remain research rows. Saved routes are snapshots, not verified deliverability.
Older lists are not automatically backfilled with contacts previously lost.
This server behavior was available with the published 1.4.0 CLI and MCP server;
saving a research list creates no campaign and sends nothing.
Resumable reviews (since 1.8.0)
npx --yes @dmfaster/[email protected] companies fit run --input run.json --until-complete --max-seconds 1800
npx --yes @dmfaster/[email protected] companies fit export fit_RETURNED_ID --output complete-review.json
run.json holds the returned runId and optional limit (1–8). Transient
retries reuse that run; repeat the command after an interruption or budget exit.
Progress goes to stderr, final JSON to stdout. Export requires a complete review,
reconciles all companies at one version, and refuses file overwrite. It produces
no partial file. For status, recovery, cancellation, cohorts, historical copy,
calendar and call reads, use the generated describe and --input FILE commands.
Calendar booking sends invitations and needs exact user authorization plus owner
calendar scopes. Existing grants must be upgraded through the browser first.