CLI Reference

The sure-cli tool wraps the SurelyCrm JSON API so you can manage customers, leads, workflows, and support records from the terminal or shell scripts without writing HTTP calls by hand. This guide covers version 1.3.0.

Installation

The CLI is published to the npm registry. Install it globally:

npm install -g @surelycrm/cli

Or run it once without installing:

npx @surelycrm/cli --help

To develop locally, the CLI source also lives in the Sure.Cli folder of the repository. Install its dependencies and link the command:

cd Sure.Cli
npm install
npm link

After linking, the sure-cli command is available globally.

Configuration

Before running any command, initialise the CLI with the API base URL and your API key. Configuration is stored in ~/.surecli/config.json.

Init

Property	Value
Command	sure-cli init
Purpose	Store the API base URL and API key

Options

Option	Required	Description
--url	Yes	Base URL of the SurelyCrm site, e.g. https://app.surelycrm.co.uk/
--api-key	Yes	API key GUID from Settings > Application Settings

Example

sure-cli init \
  --url https://app.surelycrm.co.uk/ \
  --api-key 550e8400-e29b-41d4-a716-446655440000

Show Config

sure-cli config

Prints the currently stored configuration.

Customer Commands

All customer actions are grouped under sure-cli customer (alias sure-cli customers). Every command that needs a request body accepts --template, --data, or uses the bundled default template. Lead conversion is documented separately because it accepts no mapping payload.

Get Customer

Retrieves a single customer record by GUID, email address, or reference number. Only one lookup option can be used at a time.

Property	Value
Command	sure-cli customer get
API endpoints	GET /Api/customer/{id}, GET /Api/customer/byEmail/{emailAddress}, GET /Api/customer/reference/{referenceNumber}

Options

Option	Required	Description
--id	One of --id, --email, or --reference	Customer GUID
--email	One of --id, --email, or --reference	Customer email address
--reference	One of --id, --email, or --reference	Customer reference number

Examples

sure-cli customer get --id 550e8400-e29b-41d4-a716-446655440000
sure-cli customer get --email john@example.com
sure-cli customer get --reference CUS-2025-00001

Add Customer

Creates a new customer. Uses the bundled template by default, or a custom JSON file or inline payload.

Property	Value
Command	sure-cli customer add
API endpoint	POST /Api/customer

Options

Option	Required	Description
--template	No	Path to a JSON customer template file
--data	No	Inline JSON payload

Examples

# Use the default bundled template
sure-cli customer add

# Use a custom template
sure-cli customer add --template ./my-customer.json

# Inline JSON
sure-cli customer add --data '{"title":"Mrs","firstname":"Jane","surname":"Smith","emailAddress":"jane@example.com"}'

Update Customer

Updates an existing customer by GUID, reference, or email. The resolved identifier is injected into the payload automatically.

Property	Value
Command	sure-cli customer update
API endpoint	PUT /Api/customer/{id}

Options

Option	Required	Description
--id	One of --id, --email, or --reference	Customer GUID
--email	One of --id, --email, or --reference	Customer email address
--reference	One of --id, --email, or --reference	Customer reference number
--template	No	Path to a JSON customer template file
--data	No	Inline JSON payload

Example

sure-cli customer update \
  --id 550e8400-e29b-41d4-a716-446655440000 \
  --data '{"title":"Mr","firstname":"Johnny","surname":"Davies","emailAddress":"johnny@example.com"}'

Change Customer Status

Changes the status of a customer identified by GUID, reference, or email.

Property	Value
Command	sure-cli customer change-status
API endpoint	POST /Api/customer/{id}/status

Options

Option	Required	Description
--id	One of --id, --email, or --reference	Customer GUID
--email	One of --id, --email, or --reference	Customer email address
--reference	One of --id, --email, or --reference	Customer reference number
--status-id	Yes*	Status GUID. *Required unless already present in --data or --template.
--template	No	Path to a JSON status change template file
--data	No	Inline JSON payload

Example

sure-cli customer change-status \
  --reference CUS-2025-00001 \
  --status-id 550e8400-e29b-41d4-a716-446655440001

Start Customer Workflow

Starts a workflow instance for a customer identified by GUID, reference, or email. Either --workflow-id or --workflow-name is required.

Property	Value
Command	sure-cli customer start-workflow
API endpoint	POST /Api/customer/{id}/workflow

Options

Option	Required	Description
--id	One of --id, --email, or --reference	Customer GUID
--email	One of --id, --email, or --reference	Customer email address
--reference	One of --id, --email, or --reference	Customer reference number
--workflow-id	One of --workflow-id or --workflow-name	Workflow GUID
--workflow-name	One of --workflow-id or --workflow-name	Workflow name
--context-data	No	JSON context data. Defaults to "{}".
--template	No	Path to a JSON workflow start template file
--data	No	Inline JSON payload

Examples

sure-cli customer start-workflow \
  --email john@example.com \
  --workflow-id 550e8400-e29b-41d4-a716-446655440001

sure-cli customer start-workflow \
  --reference CUS-2025-00001 \
  --workflow-name "Welcome Sequence"

Get Customers by Age

Property	Value
Command	sure-cli get-customers-by-age
API endpoint	GET /Api/customers/byAge?age={age}&comparison={comparison}

Options

Option	Required	Description
--age	Yes	Age value to compare
--comparison	No	One of equal, greater, less, greaterthanorequal, or lessthanorequal. Defaults to equal.

Campaign Commands

Campaigns are managed with sure-cli campaign (alias sure-cli campaigns). Campaigns can be looked up by GUID, reference code, or name. When a reference code is omitted on create, a unique code is generated automatically from the campaign name.

Get Campaign

Retrieves a single campaign by GUID, reference code, or name.

Property	Value
Command	sure-cli campaign get
API endpoints	GET /Api/campaign/{id}, GET /Api/campaign/reference/{referenceCode}, GET /Api/campaign/byName/{name}

Options

Option	Required	Description
--id	One of --id, --reference, or --name	Campaign GUID
--reference	One of --id, --reference, or --name	Campaign reference code
--name	One of --id, --reference, or --name	Campaign name

Examples

sure-cli campaign get --id 550e8400-e29b-41d4-a716-446655440000
sure-cli campaign get --reference CMP-2026-00001
sure-cli campaign get --name "Summer Campaign"

List Campaigns

Property	Value
Command	sure-cli campaign list
API endpoint	GET /Api/campaigns

Add Campaign

Creates a new campaign. The reference code is optional; leave it blank or omit it to auto-generate a code such as CMP-2026-00001.

Property	Value
Command	sure-cli campaign add
API endpoint	POST /Api/campaign

Options

Option	Required	Description
--template	No	Path to a JSON campaign template file
--data	No	Inline JSON payload

Examples

# Use the default bundled template
sure-cli campaign add

# Inline JSON with an explicit reference code
sure-cli campaign add --data '{"name":"Summer Campaign","referenceCode":"SUM-2026-001","campaignLocationId":"550e8400-e29b-41d4-a716-446655440010","status":"New"}'

# Auto-generate the reference code
sure-cli campaign add --data '{"name":"Summer Campaign","campaignLocationId":"550e8400-e29b-41d4-a716-446655440010"}'

Update Campaign

Updates an existing campaign by GUID, reference code, or name. The resolved identifier is injected into the payload automatically.

Property	Value
Command	sure-cli campaign update
API endpoint	PUT /Api/campaign/{id}

Options

Option	Required	Description
--id	One of --id, --reference, or --name	Campaign GUID
--reference	One of --id, --reference, or --name	Campaign reference code
--name	One of --id, --reference, or --name	Campaign name
--template	No	Path to a JSON campaign template file
--data	No	Inline JSON payload

Example

sure-cli campaign update \
  --reference CMP-2026-00001 \
  --data '{"status":"InProgress"}'

Campaign Location Commands

Campaign locations are managed with sure-cli location (alias sure-cli locations). Locations are looked up by GUID.

Get Campaign Location

Property	Value
Command	sure-cli location get
API endpoint	GET /Api/campaign-location/{id}

Options

Option	Required	Description
--id	Yes	Campaign location GUID

List Campaign Locations

Property	Value
Command	sure-cli location list
API endpoint	GET /Api/campaign-locations

Add Campaign Location

Property	Value
Command	sure-cli location add
API endpoint	POST /Api/campaign-location

Options

Option	Required	Description
--template	No	Path to a JSON location template file
--data	No	Inline JSON payload

Example

sure-cli location add --data '{"name":"Manchester","description":"North West region","isActive":true}'

Update Campaign Location

Property	Value
Command	sure-cli location update
API endpoint	PUT /Api/campaign-location/{id}

Options

Option	Required	Description
--id	Yes	Campaign location GUID
--template	No	Path to a JSON location template file
--data	No	Inline JSON payload

Lead Commands

Leads are managed with sure-cli lead (alias sure-cli leads). Discover exact records by status and opaque external reference. External references are integration identities, separate from display/reference numbers and CRM IDs. When creating or updating a Lead, select its campaign by GUID, name or reference code.

Discover Leads by Status

sure-cli lead list --status BuildFailed
sure-cli lead list --status "Needs Review" --page-size 5 --cursor '<nextCursor>'
sure-cli lead list --status BuildFailed --all
sure-cli lead get --external-reference 'lead_opaque_reference'

--status is required and trimmed. It accepts a tenant-local Lead status name or Lead status GUID; invalid status fails without an unfiltered retry. Default output is one JSON page, with only these fields per Lead:

{
  "leads": [
    {
      "externalReference": "lead_opaque_reference",
      "status": "BuildFailed",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ],
  "nextCursor": null
}

A valid status with no matches succeeds with {"leads":[],"nextCursor":null}. The default page size is 20; --page-size accepts decimal integers 1–20. Pass the previous nextCursor unchanged with --cursor for continuation; tokens must be nonblank and at most 2,048 characters.

--all walks remaining pages sequentially, optionally from --cursor, until the cursor is null. Limits are 1,000 requests and 10 MiB cumulative response bytes. If they prevent completion, use manual pagination. Repeated cursors, duplicate references, malformed responses and later-page errors fail without partial stdout. Each request has a 30-second timeout, 1 MiB success-body limit and 8 KiB error-body limit. There are no automatic retries or redirects. Concurrent writes can change page membership or remove later detail; traversal is not a database snapshot.

The configured host selects the tenant and its apiKey authenticates both reads. Listing requires AutomatedSampleSiteClaim; exact reference detail independently requires SalesBrief. Failures exit nonzero with bounded stderr and no raw error body: 400 means invalid input, 401 authentication failed, and 404 unavailable, missing or disabled access.

Reference detail returns exactly externalReference, businessName, salesBrief, contactEmail, contactPhone, preferredSite and customFields. Nullable strings stay null. Custom fields contain stored string values for active Lead definitions by name, or an empty object. This explicit detail may contain private data. See the list API and reference detail API.

Edit and Read Lead Fields

Use exactly one --id or --email. Updates require a local UTF-8 JSON file, so private values need not appear in arguments.

sure-cli lead update-fields --id {guid} --file ./lead-fields.json
sure-cli lead get-fields --id {guid}
sure-cli lead update-fields --email lead@example.test --file ./lead-fields.json
sure-cli lead get-fields --email lead@example.test

The file accepts salesBrief and/or customFields:

{
  "salesBrief": "Prepared sales brief",
  "customFields": { "Domain": "example.test", "Approved": "false", "OldValue": null }
}

Omitted fields and omitted custom keys preserve stored values. Brief text is limited to 8,000 raw characters. Strings are trimmed by the server; null or blank text clears the brief or deletes only the named custom value. Custom keys are exact active Lead definition Names; values are strings or null. Use "false" for an unchecked checkbox, not a JSON boolean.

An empty operation, unknown property, duplicate key, null custom object or wrong JSON value shape fails. The CLI validates file shape before email lookup; the server validates names and types and rejects a whole mixed edit if any entry is invalid. No defaults or omitted required values are filled.

Both commands require Leads and the configured tenant API key. Brief edits require SalesBrief; custom edits require LeadTagsAndCustomFields. Readback includes only enabled groups: nullable salesBrief and stored active values in customFields, or an empty object. Disabled groups are omitted. Updates print {"success":true}. Keep private readback out of shared logs; failure output does not print API error bodies.

See the Lead Fields API for validation and status codes. Existing lead update remains a full standard-field update and cannot write SalesBrief.

Get Lead

Use exactly one selector: --external-reference for the seven-field detail described above, or --id/--email for legacy sensitive full-record output. Email can select only one of several same-email Leads; use discovery and an exact reference to distinguish them.

Property	Value
Command	sure-cli lead get
API endpoints	GET /Api/lead/{id}, GET /Api/lead/byEmail/{emailAddress}, GET /api/external/leads/{externalReference}

Options

Option	Required	Description
--id	Exactly one selector	Lead GUID
--email	Exactly one selector	Lead email address
--external-reference	Exactly one selector	Opaque reference returned by discovery

Examples

sure-cli lead get --id 550e8400-e29b-41d4-a716-446655440000
sure-cli lead get --email lead@example.test
sure-cli lead get --external-reference lead_opaque_reference

Add Lead

Creates a new lead with the tenant's Lead status named New. This status is tenant data seeded for compatibility; if it is missing, creation fails until the status is restored.

Property	Value
Command	sure-cli lead add
API endpoint	POST /Api/lead

Options

Option	Required	Description
--campaign-id	No*	Campaign GUID. *Required unless campaignId is supplied in --data/--template, or another campaign selector is used.
--campaign-name	No*	Campaign name. Resolved to a GUID before the request is sent.
--campaign-reference	No*	Campaign reference code. Resolved to a GUID before the request is sent.
--template	No	Path to a JSON lead template file
--data	No	Inline JSON payload

Examples

# Assign to a campaign by GUID
sure-cli lead add --campaign-id 550e8400-e29b-41d4-a716-446655440000 --data '{"businessName":"Example Business","contactPerson":"Jane Smith","contactEmail":"jane@example.com","contactPhone":"07700900456"}'

# Assign to a campaign by name
sure-cli lead add --campaign-name "Summer Campaign" --data '{"businessName":"Example Business","contactPerson":"Jane Smith","contactEmail":"jane@example.com","contactPhone":"07700900456"}'

# Assign to a campaign by reference code
sure-cli lead add --campaign-reference CMP-2026-00001 --data '{"businessName":"Example Business","contactPerson":"Jane Smith","contactEmail":"jane@example.com","contactPhone":"07700900456"}'

# Provide campaignId directly in the payload
sure-cli lead add --data '{"campaignId":"550e8400-e29b-41d4-a716-446655440000","businessName":"Example Business","contactPerson":"Jane Smith","contactEmail":"jane@example.com","contactPhone":"07700900456"}'

Update Lead

Updates an existing lead by GUID or email. The campaign can be changed using --campaign-id, --campaign-name, or --campaign-reference.

Property	Value
Command	sure-cli lead update
API endpoint	PUT /Api/lead/{id}

Options

Option	Required	Description
--id	One of --id or --email	Lead GUID
--email	One of --id or --email	Lead email address
--campaign-id	No	New campaign GUID
--campaign-name	No	New campaign name. Resolved to a GUID before the request is sent.
--campaign-reference	No	New campaign reference code. Resolved to a GUID before the request is sent.
--template	No	Path to a JSON lead template file
--data	No	Inline JSON payload

Example

sure-cli lead update --email jane@example.com --campaign-reference CMP-2026-00001 --data '{"businessName":"Example Business Ltd"}'

Change Lead Status

Changes the status of a lead. Provide a Lead status name or the matching status GUID (for example the tenant's Processing status).

Property	Value
Command	sure-cli lead change-status
API endpoint	POST /Api/lead/{id}/status

Options

Option	Required	Description
--id	One of --id or --email	Lead GUID
--email	One of --id or --email	Lead email address
--status	Yes*	New Lead status name or matching Lead status GUID. *Required unless already present in --data or --template.
--notes	No	Optional notes for the activity log
--template	No	Path to a JSON lead status change template file; the default still uses Processing.
--data	No	Inline JSON payload

Example

sure-cli lead change-status --email lead@example.com --status Processing --notes "Called and left voicemail"

Start Lead Workflow

Starts a workflow instance for a lead. Either --workflow-id or --workflow-name is required.

Property	Value
Command	sure-cli lead start-workflow
API endpoint	POST /Api/lead/{id}/workflow

Options

Option	Required	Description
--id	One of --id or --email	Lead GUID
--email	One of --id or --email	Lead email address
--workflow-id	One of --workflow-id or --workflow-name	Workflow GUID
--workflow-name	One of --workflow-id or --workflow-name	Workflow name
--context-data	No	JSON context data. Defaults to "{}".
--template	No	Path to a JSON workflow start template file
--data	No	Inline JSON payload

Convert Lead

Converts a lead to a customer using the tenant's saved Lead Conversion Configuration. The mapping is loaded and applied silently. You can optionally assign a Customer status after conversion.

Property	Value
Command	sure-cli lead convert
API endpoint	POST /Api/lead/{id}/convert

Options

Option	Required	Description
--id	One of --id or --email	Lead GUID
--email	One of --id or --email	Lead email address
--new-status-id	No	Customer status GUID to assign after conversion

Use exactly one selector. With --email, the CLI resolves the Lead first and then calls POST /Api/lead/{id}/convert. No mapping JSON, template, or confirmation is sent. The API and MVC conversion paths use the same server-side apply operation, so they persist equivalent results.

Example

sure-cli lead convert --email lead@example.com --new-status-id 550e8400-e29b-41d4-a716-446655440002

Opportunity Commands

Manage the sales pipeline with sure-cli opportunity (alias sure-cli opportunities). Opportunities are linked to leads and track deal value, stage, probability, and expected close date.

List Opportunities

Property	Value
Command	sure-cli opportunity list
API endpoint	GET /Api/opportunities

Options

Option	Required	Description
--lead-id	No	Filter by lead GUID
--lead-email	No	Filter by lead email address
--stage	No	Filter by opportunity stage
--status	No	Filter by opportunity status
--search	No	Search term
--page	No	Page number (default 1)

Examples

sure-cli opportunity list
sure-cli opportunity list --lead-email lead@example.com
sure-cli opportunity list --stage Proposal --status Open

Get Opportunity

Property	Value
Command	sure-cli opportunity get
API endpoint	GET /Api/opportunities/{id}

Example

sure-cli opportunity get --id 550e8400-e29b-41d4-a716-446655440000

Add Opportunity

Property	Value
Command	sure-cli opportunity add
API endpoint	POST /Api/opportunities

Options

Option	Required	Description
--lead-id or --lead-email	Yes	Lead identifier
--title	Yes*	Opportunity title (*or include in --data/--template)
--value	No	Deal value
--stage	No	Stage (default Prospecting)
--status	No	Status (default Open)
--expected-close	No	Expected close date (yyyy-mm-dd)
--template	No	Path to a JSON opportunity template file
--data	No	Inline JSON payload

Examples

sure-cli opportunity add --lead-email lead@example.com --title "Website redesign" --value 5000
sure-cli opportunity add --lead-id 550e8400-e29b-41d4-a716-446655440000 --data '{"title":"Website redesign","value":5000,"probability":50}'

Update Opportunity

Property	Value
Command	sure-cli opportunity update
API endpoint	PUT /Api/opportunities/{id}

Example

sure-cli opportunity update --id 550e8400-e29b-41d4-a716-446655440000 --stage Proposal --value 7500

Change Opportunity Stage

Property	Value
Command	sure-cli opportunity change-stage
API endpoint	POST /Api/opportunities/{id}/stage

Example

sure-cli opportunity change-stage --id 550e8400-e29b-41d4-a716-446655440000 --stage ClosedWon --notes "Verbal agreement received"

Lead Task Commands

Manage tasks linked to leads with sure-cli task (alias sure-cli tasks). Tasks support assignment, due dates, priorities, and status tracking.

List Lead Tasks

Property	Value
Command	sure-cli task list
API endpoint	GET /Api/lead-tasks

Options

Option	Required	Description
--lead-id	No	Filter by lead GUID
--lead-email	No	Filter by lead email address
--assigned-to	No	Filter by assigned user GUID
--status	No	Filter by task status
--priority	No	Filter by task priority
--search	No	Search term
--page	No	Page number (default 1)

Examples

sure-cli task list
sure-cli task list --lead-email lead@example.com --status NotStarted
sure-cli task list --assigned-to 550e8400-e29b-41d4-a716-446655440001

Get Lead Task

Property	Value
Command	sure-cli task get
API endpoint	GET /Api/lead-tasks/{id}

Example

sure-cli task get --id 550e8400-e29b-41d4-a716-446655440000

Add Lead Task

Property	Value
Command	sure-cli task add
API endpoint	POST /Api/lead-tasks

Options

Option	Required	Description
--lead-id or --lead-email	Yes	Lead identifier
--title	Yes*	Task title (*or include in --data/--template)
--assigned-to	No	Assigned user GUID
--status	No	Status (default NotStarted)
--priority	No	Priority (default Normal)
--due-date	No	Due date (yyyy-mm-dd)
--template	No	Path to a JSON task template file
--data	No	Inline JSON payload

Examples

sure-cli task add --lead-email lead@example.com --title "Follow up call" --priority High --due-date 2026-08-10
sure-cli task add --lead-id 550e8400-e29b-41d4-a716-446655440000 --data '{"title":"Follow up call","priority":"High","dueDate":"2026-08-10"}'

Update Lead Task

Property	Value
Command	sure-cli task update
API endpoint	PUT /Api/lead-tasks/{id}

Example

sure-cli task update --id 550e8400-e29b-41d4-a716-446655440000 --status InProgress

Change Lead Task Status

Property	Value
Command	sure-cli task change-status
API endpoint	POST /Api/lead-tasks/{id}/status

Example

sure-cli task change-status --id 550e8400-e29b-41d4-a716-446655440000 --status Completed

Workflow Commands

Inspect, replace, and change the lifecycle of the configured tenant's workflow definitions. These commands use the tenant API key and print machine-readable JSON on stdout. They never start an instance. The Supplier record type is reported as the canonical Company value. The configured host selects the tenant; its administrative API key is required, and a browser session is insufficient. Key-only writes use the tenant-local non-login audit actor; no interactive tenant user is required. There is no workflow delete command.

Deploy and verify the Workflow Definition API on the server before publishing or using the matching CLI. Older servers return bounded HTTP failures; the CLI never falls back to browser actions or database access. Existing Customer/Lead instance-start commands remain separate.

List Workflows

Lists workflow definitions for the configured tenant, including inactive ones. Output is { items, page, pageSize, hasMore }, ordered by name then id. No automatic paging is performed. An empty page succeeds with items: []. The CLI clamps a positive page size above 100 to 100; the API rejects sizes above 100. The page offset must fit 2,147,483,647. Separate pages can shift if definitions change between requests.

Property	Value
Command	sure-cli workflow list
API endpoint	GET /api/workflows

Options

Option	Default	Description
--page	1	Page number (1 or greater)
--page-size	50	Page size, capped at 100

Examples

sure-cli workflow list
sure-cli workflow list --page 2 --page-size 10

Get Workflow

Returns one complete definition, including every stage, its type and action configuration, conditions and modes, branch rules and fallback, waits, next/otherwise/failure routes, and layout positions, plus the trigger and its conditions. Redirect the output to a file to keep a private export.

Property	Value
Command	sure-cli workflow get
API endpoint	GET /api/workflows/{id}

Options

Option	Required	Description
--id	Yes	Workflow GUID

Examples

sure-cli workflow get --id 550e8400-e29b-41d4-a716-446655440000
sure-cli workflow get --id 550e8400-e29b-41d4-a716-446655440000 > definition.json

Apply Workflow

Creates or updates a workflow from a JSON definition. Supply exactly one of --file or --data. The payload is the same shape returned by workflow get: an absent, null, or all-zero GUID id creates a new Draft, inactive workflow, while a non-zero GUID id updates that tenant's workflow and preserves its lifecycle state. Include both stages and trigger (use [] and null to clear them), and remember read-only activation fields are ignored. Apply is a full replacement, so an edited export re-applied with its id converges the definition. A retained trigger keeps its identity even when edited; its conditions are replaced. Removing a trigger referenced by any queue row (including completed/failed rows), or a stage with execution history, fails with a bounded conflict. The definition must be a JSON object of at most 1 MiB; a malformed or oversized definition fails before any request is sent.

Property	Value
Command	sure-cli workflow apply
API endpoint	POST /api/workflows/apply

Options

Option	Required	Description
--file	One of --file or --data	Path to a JSON definition file
--data	One of --file or --data	Inline JSON definition

Examples

sure-cli workflow apply --data \
  '{"name":"Welcome","stages":[],"trigger":null}'
sure-cli workflow get --id 550e8400-e29b-41d4-a716-446655440000 > definition.json
sure-cli workflow apply --file definition.json

The inline example creates; applying an export that still contains its id updates the same workflow. Remove the id to copy the definition into a new workflow, choose fresh stage IDs and update all graph references consistently. Removing only the workflow ID conflicts when its stage IDs already belong to another workflow. For another tenant, also reconcile templates, typed statuses, custom fields, and child workflows; nothing is automatically matched by name.

Include the exported record type on update. A workflow with stages or active state keeps its stored type; an empty inactive workflow can change type and defaults an omitted type to Customer. Apply requires no new update licence check; creation requires Workflow Builder licensing. Unknown IDs return 404, never create. Concurrent updates serialize, with the last successful write winning; there is no stale-edit detection, merge, or version precondition.

Activate or Deactivate Workflow

Lifecycle changes are explicit commands. Activation validates the stored definition and applies the Workflow Builder license and capacity rules. A definition with no stages cannot be activated and returns the definition conflict. Repeating a requested state succeeds without consuming another activation slot. Actual activation yields Active/true; deactivation yields Paused/false without a licence check. Deactivation preserves queue rows and running instances, but a worker attempting a pending start while inactive marks it Failed. Reactivation does not retry failed queue items.

Command	API endpoint	Option
sure-cli workflow activate	POST /api/workflows/{id}/activate	--id <guid>
sure-cli workflow deactivate	POST /api/workflows/{id}/deactivate	--id <guid>

sure-cli workflow activate --id 550e8400-e29b-41d4-a716-446655440000
sure-cli workflow deactivate --id 550e8400-e29b-41d4-a716-446655440000

Each successful command prints { id, status, isActive } as JSON. Existing instances use the current definition rather than a versioned snapshot, so changing later stages can affect their next processing. Lifecycle requests are never retried automatically.

Errors

Successful output is valid JSON on stdout with no banners. Failures exit non-zero with a short message on stderr; error bodies are bounded at 8 KiB and a successful response over 1 MiB fails without printing a truncated definition. A server error message is limited to 300 characters on stderr. Requests use a 30-second default deadline and never follow redirects, so the API key is never forwarded to another host. Workflow writes, including lifecycle changes, are never retried automatically. A deadline or connection failure does not prove rollback. After an uncertain create, inspect list/get before submitting again: creation without an ID can create duplicates. For an uncertain update or lifecycle call, get the current state before deciding whether to reapply. Server errors and bounds are documented in the Workflow Definition API.

Exports can contain sensitive action settings. Keep files private and avoid inline secrets in shell history. Transport tests can override the deadline with a positive integer SURE_CLI_REQUEST_TIMEOUT_MS value in milliseconds. The operator journey covers inspect, create, edit/reapply, activate, and deactivate for all three record types.

Support Commands

Get Support Tickets

Gets support tickets in one of three modes. Pass a ticket --id to fetch a single ticket with its messages. Pass a customer identifier (--customer-id or --customer-email) to list all tickets for that customer. Or use the global list filters --new or --recently-replied. Only one mode can be used at a time.

Property	Value
Command	sure-cli get-support-tickets
API endpoints	GET /Api/support/tickets/{id}, GET /Api/support/tickets

Options

Option	Required	Description
--id	One mode selector only	Support ticket GUID
--customer-id	One mode selector only	Customer GUID
--customer-email	One mode selector only	Customer email address
--new	One mode selector only	Return open tickets ordered by creation date
--recently-replied	One mode selector only	Return tickets with messages in the recent period
--hours	No	Number of hours to look back for recently replied tickets. Defaults to 24.
--page	No	Page number. Defaults to 1.
--page-size	No	Page size. Defaults to 25.

Examples

# Get a single ticket by support ticket id
sure-cli get-support-tickets --id 550e8400-e29b-41d4-a716-446655440000

# Get all tickets for a customer by customer id
sure-cli get-support-tickets --customer-id 550e8400-e29b-41d4-a716-446655440001

# Get all tickets for a customer by email
sure-cli get-support-tickets --customer-email john@example.com

# Global list filters
sure-cli get-support-tickets --new
sure-cli get-support-tickets --recently-replied
sure-cli get-support-tickets --recently-replied --hours 48 --page 1 --page-size 10

Reply to Support Ticket

Adds a staff reply to an existing support ticket. The message can be supplied inline, from the bundled template, or from a custom JSON file.

Property	Value
Command	sure-cli reply-to-ticket
API endpoint	POST /Api/support/tickets/{id}/reply

Options

Option	Required	Description
--id	Yes	Support ticket GUID
--message	One of --message, --template, or --data	Reply message text
--template	One of --message, --template, or --data	Path to a JSON reply template file
--data	One of --message, --template, or --data	Inline JSON reply payload
--internal	No	Mark the reply as internal-only
--close	No	Close the ticket after replying

Examples

sure-cli reply-to-ticket --id 550e8400-e29b-41d4-a716-446655440000 --message "We are looking into this."
sure-cli reply-to-ticket --id 550e8400-e29b-41d4-a716-446655440000 --message "Resolved." --close
sure-cli reply-to-ticket --id 550e8400-e29b-41d4-a716-446655440000 --template ./my-reply.json

JSON Templates

The CLI ships with reusable JSON templates in the Sure.Cli/templates directory. You can copy and edit them for your own use, or pass inline JSON with --data.

customer.json

Default template used by sure-cli customer add and sure-cli customer update when no --data or --template option is supplied.

{
  "title": "Mr",
  "firstname": "John",
  "surname": "Davies",
  "referenceNumber": "",
  "address1": "123 High Street",
  "address2": "",
  "address3": "",
  "address4": "",
  "town": "Manchester",
  "city": "Greater Manchester",
  "postcode": "M1 1AA",
  "homePhone": "",
  "mobilePhone": "07700900123",
  "emailAddress": "john.davies@example.com",
  "notificationsEnabled": true,
  "importantDate": null,
  "dateOfBirth": null,
  "website": "",
  "statusId": null,
  "ownerId": null,
  "referredBy": "",
  "customFields": {}
}

campaign.json

Default template used by sure-cli campaign add and sure-cli campaign update when no --data or --template option is supplied. Leave referenceCode blank to let the API generate one.

{
  "name": "Summer Campaign",
  "referenceCode": "",
  "campaignLocationId": "00000000-0000-0000-0000-000000000000",
  "status": "New"
}

campaign-location.json

Default template used by sure-cli location add and sure-cli location update when no --data or --template option is supplied.

{
  "name": "Manchester",
  "description": "North West region",
  "isActive": true
}

lead.json

Default template used by sure-cli lead add and sure-cli lead update when no --data or --template option is supplied.

{
  "campaignId": "00000000-0000-0000-0000-000000000000",
  "businessName": "Example Business Ltd",
  "contactPerson": "Jane Smith",
  "contactEmail": "jane.smith@example.com",
  "contactPhone": "07700900456",
  "websiteUrl": "https://www.example.com",
  "preferredSite": "",
  "sampleSiteUrls": ""
}

status-change.json

Template for the sure-cli customer change-status payload.

{
  "statusId": "00000000-0000-0000-0000-000000000000"
}

lead-status-change.json

Template for the sure-cli lead change-status payload.

{
  "status": "Processing",
  "notes": ""
}

workflow-start.json

Template for the sure-cli customer start-workflow and sure-cli lead start-workflow payloads.

{
  "workflowId": "00000000-0000-0000-0000-000000000000",
  "workflowName": "",
  "contextData": "{}"
}

opportunity.json

Default template used by sure-cli opportunity add and sure-cli opportunity update when no --data or --template option is supplied.

{
  "title": "",
  "description": "",
  "value": 0,
  "currency": "GBP",
  "probability": 0,
  "stage": "Prospecting",
  "status": "Open",
  "expectedCloseDate": null,
  "actualCloseDate": null,
  "ownerId": null
}

task.json

Default template used by sure-cli task add and sure-cli task update when no --data or --template option is supplied.

{
  "title": "",
  "description": "",
  "assignedToUserId": null,
  "status": "NotStarted",
  "priority": "Normal",
  "dueDate": null
}

support-reply.json

Template for the reply-to-ticket command payload.

{
  "message": "",
  "isInternal": false,
  "closeAfterReply": false
}

Exit Codes

Code	Meaning
0	Success
1	Configuration missing, validation error, or non-2xx HTTP response

Example Session

# 1. Configure the CLI
sure-cli init --url https://app.surelycrm.co.uk/ --api-key 550e8400-e29b-41d4-a716-446655440000

# 2. Create a customer
sure-cli customer add --template ./templates/customer.json

# 3. Fetch the customer
sure-cli customer get --id 550e8400-e29b-41d4-a716-446655440000
sure-cli customer get --email john@example.com
sure-cli customer get --reference CUS-2025-00001

# 4. Change the customer's status
sure-cli customer change-status \
  --id 550e8400-e29b-41d4-a716-446655440000 \
  --status-id 550e8400-e29b-41d4-a716-446655440002

# 5. Start a workflow for the customer
sure-cli customer start-workflow \
  --reference CUS-2025-00001 \
  --workflow-name "Welcome Sequence"

# 6. Add a campaign location
sure-cli location add --data '{"name":"Manchester","description":"North West region","isActive":true}'

# 7. Add a campaign (reference code auto-generated)
sure-cli campaign add --data '{"name":"Summer Campaign","campaignLocationId":"550e8400-e29b-41d4-a716-446655440020","status":"New"}'

# 8. Fetch the campaign by reference code
sure-cli campaign get --reference CMP-2026-00001

# 9. Add and manage a lead using the campaign reference code
sure-cli lead add --campaign-reference CMP-2026-00001 --data '{"businessName":"Acme Ltd","contactPerson":"Jane Smith","contactEmail":"jane@example.com","contactPhone":"07700900456"}'
sure-cli lead get --email jane@example.com
sure-cli lead change-status --email jane@example.com --status Processing
sure-cli lead convert --email jane@example.com --new-status-id 550e8400-e29b-41d4-a716-446655440002

# 10. Manage opportunities for the lead
sure-cli opportunity add --lead-email jane@example.com --title "Website redesign" --value 5000 --stage Prospecting
sure-cli opportunity list --lead-email jane@example.com
sure-cli opportunity change-stage --id 550e8400-e29b-41d4-a716-446655440030 --stage ClosedWon --notes "Verbal agreement received"

# 11. Manage tasks for the lead
sure-cli task add --lead-email jane@example.com --title "Follow up call" --priority High --due-date 2026-08-10
sure-cli task list --lead-email jane@example.com --status NotStarted
sure-cli task change-status --id 550e8400-e29b-41d4-a716-446655440031 --status Completed

# 12. Find customers older than 30
sure-cli get-customers-by-age --age 30 --comparison greater

# 13. List and reply to support tickets
sure-cli get-support-tickets --id 550e8400-e29b-41d4-a716-446655440003
sure-cli get-support-tickets --customer-id 550e8400-e29b-41d4-a716-446655440000
sure-cli get-support-tickets --customer-email john@example.com
sure-cli get-support-tickets --new
sure-cli reply-to-ticket --id 550e8400-e29b-41d4-a716-446655440003 --message "We are looking into this."