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.

Prerequisites: Node.js 18 or later is required. The CLI communicates with the same /Api/ endpoints as the raw HTTP API, so an API key is required.

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.

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). Leads do not have reference numbers, so lookups use --id or --email only. When creating or updating a lead, the campaign can be specified by GUID, name, or reference code.

Get Lead

Retrieves a single lead record by GUID or email address.

Property	Value
Command	`sure-cli lead get`
API endpoints	`GET /Api/lead/{id}`, `GET /Api/lead/byEmail/{emailAddress}`

Options

Option	Required	Description
`--id`	One of `--id` or `--email`	Lead GUID
`--email`	One of `--id` or `--email`	Lead email address

Examples

sure-cli lead get --id 550e8400-e29b-41d4-a716-446655440000
sure-cli lead get --email lead@example.com

Add Lead

Creates a new lead. The lead is created with status New.

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 the status name (for example Processing, Converted, Rejected).

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. *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
`--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. A unique reference number is generated automatically from the campaign prefix. 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
`--template`	No	Path to a JSON conversion template file
`--data`	No	Inline JSON payload

Example

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

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": "{}"
}

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. Find customers older than 30
sure-cli get-customers-by-age --age 30 --comparison greater

# 11. 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."

Need help? Run any command with --help for usage details, or contact SurelyCrm Support.