jazzhq-cli

Command-line tool for managing customer and partner data using the JazzHQ APIs.

Install

uv tool install jazzhq-cli
# or
pipx install jazzhq-cli
# or, inside a virtual environment
pip install jazzhq-cli

This puts a jazzhq-cli command on your PATH.

Configure

jazzhq-cli authenticates with a vendor API key, sent as the X-API-KEY header on every request. Set it, along with the API host, as environment variables:

export JAZZHQ_API_KEY="your-vendor-api-key"
export JAZZHQ_API_BASE_URL="https://api.jazzhq.ai"

Or override either one per-command with --api-key / --base-url, which take precedence over the environment variables:

jazzhq-cli partner list --api-key "your-vendor-api-key" --base-url "https://api.jazzhq.ai"

If neither the environment variable nor the flag is set, the command exits with a configuration error before making any request.

Commands

Every command prints the raw JSON API response body to stdout on success. Errors go to stderr, including any field-level validation errors returned by the API.

All commands accept --api-key and --base-url as described above.

partner invite

Invite a new partner.

Flag	Required	Description
--company-name	yes	Partner's company name
--contact-name	yes	Primary contact's full name
--contact-email-address	yes	Primary contact's email address
--contact-phone	no	Primary contact's phone number
--type	no	One of REFERRAL_PARTNER, AFFILIATE_PARTNER, RESELLER, DISTRIBUTOR
--user	no	A person to invite inside the partner company, as comma-separated key=value pairs. Repeatable.
--users-json	no	A JSON array of user objects, instead of --user

jazzhq-cli partner invite \
  --company-name "Acme Inc" \
  --contact-name "Jane Doe" \
  --contact-email-address "jane@acme.com" \
  --type RESELLER

To invite several people at once, repeat --user. Valid keys are firstName, lastName, emailAddress, phoneNumber, and jobTitle; firstName and emailAddress are required on each.

jazzhq-cli partner invite \
  --company-name "Acme Inc" \
  --contact-name "Jane Doe" \
  --contact-email-address "jane@acme.com" \
  --user "firstName=Jane,lastName=Doe,emailAddress=jane@acme.com,jobTitle=VP Sales" \
  --user "firstName=Raj,emailAddress=raj@acme.com"

Omit --user entirely and a single user is created from the contact fields, exactly as before.

The table above covers the commonly used fields. Run jazzhq-cli partner invite --help for the full set of accepted options.

partner reinvite

Resend an invite email to an existing partner.

Argument / Flag	Required	Description
partner_id (positional)	yes	The partner's ID
--email-address	yes	Email address to resend the invite to

jazzhq-cli partner reinvite 1001 --email-address "jane@acme.com"

partner list

List partners connected to your vendor account.

Flag	Required	Default	Description
--page	no	0	Page number
--per-page	no	20	Results per page
--sort-by	no	id	Field to sort by

jazzhq-cli partner list --page 0 --per-page 20

partner add-users

Invite more people into a partner company already connected to your vendor account.

Argument / Flag	Required	Description
partner_id (positional)	yes	The partner's ID
--user	yes*	A person to invite, as comma-separated key=value pairs. Repeatable.
--users-json	yes*	A JSON array of user objects, instead of --user

* Provide one of --user or --users-json, not both.

jazzhq-cli partner add-users 1001 \
  --user "firstName=Raj,emailAddress=raj@acme.com,jobTitle=Account Executive" \
  --user "firstName=Mia,emailAddress=mia@acme.com"

This is all-or-nothing. If any email address already belongs to a user, or the same address appears twice in one request, nothing is created and the command exits 1 with a DUPLICATE_ENTRY error naming the address.

Use --users-json when a value contains a comma, since --user splits on it:

jazzhq-cli partner add-users 1001 \
  --users-json '[{"firstName":"Ann","emailAddress":"ann@acme.com","jobTitle":"VP, Sales"}]'

partner list-users

List the people inside a partner company.

Argument / Flag	Required	Default	Description
partner_id (positional)	yes		The partner's ID
--page	no	0	Page number
--per-page	no	20	Results per page
--sort-by	no	id	One of id, firstName, lastName, emailAddress, jobTitle, createdAt

jazzhq-cli partner list-users 1001 --per-page 50

Each user includes lastActiveAt, which is null until they first sign in to the partner portal — useful for telling an outstanding invite from an active user.

lead list

List a partner's leads. Archived leads are excluded unless you ask for them.

Argument / Flag	Required	Default	Description
partner_id (positional)	yes		The partner's ID
--page	no	0	Page number
--per-page	no	20	Results per page, up to 100
--sort-by	no	createdAt	One of id, createdAt, updatedAt
--sort-direction	no	desc	asc or desc
--approval-status	no		One of PENDING, APPROVED, REJECTED
--status	no		Id of a lead status dropdown value. Repeatable.
--source	no		Id of a lead source dropdown value. Repeatable.
--keyword	no		Prefix match on first name or email address
--created-at-after	no		YYYY-MM-DD
--created-at-before	no		YYYY-MM-DD
--archived	no		List archived leads instead of active ones

jazzhq-cli lead list 1001 --approval-status PENDING --per-page 50

Sorting is always tie-broken by id, so paging through a large result set never skips or repeats a lead. --per-page above 100 exits 2 without calling the API.

lead get

Fetch a single lead.

Argument / Flag	Required	Description
lead_id (positional)	yes	The lead's ID

jazzhq-cli lead get 300

A lead that belongs to a different partner returns RESOURCE_NOT_FOUND, the same as one that does not exist.

lead create

Create a lead for a partner.

Argument / Flag	Required	Description
partner_id (positional)	yes	The partner's ID
--first-name	yes	Lead's first name
--email-address	yes	Lead's email address
--company-name	yes	Lead's company name
--last-name	no	Lead's last name
--phone-number	no	Lead's phone number
--linked-in-url	no	Lead's LinkedIn profile URL
--website-url	no	Lead's company website
--company-size	no	Lead's company size, e.g. 50-100
--industry	no	Lead's industry
--job-title	no	Lead's job title
--city, --state, --country	no	Lead's location
--source	no	Id of a lead source dropdown value
--status	no	Id of a lead status dropdown value
--lead-age	no	Age of the lead in days
--products-interested	no	Products the lead is interested in
--business-impact-metrics	no	Expected business impact
--external-id	no	Your own identifier, echoed back unchanged

jazzhq-cli lead create 1001 \
  --first-name "Jane" \
  --email-address "jane@acme.com" \
  --company-name "Acme Inc" \
  --job-title "VP Sales" \
  --external-id "crm-42"

The lead is created against the partner in the path and the vendor your API key belongs to. An email address already used by another of that partner's leads exits 1 with DUPLICATE_ENTRY.

lead update

Update a lead. Only the fields you pass change; everything else keeps its stored value. Use lead replace when you want omitted fields cleared instead.

Takes lead_id as its only positional, then the same optional field flags as lead create. The lead id is unique on its own — no partner id needed. Approval state and archiving are not settable here — use lead approve, lead reject and lead archive.

jazzhq-cli lead update 300 --job-title "Head of Sales"

Passing no fields at all exits 2 rather than sending an empty request.

lead replace

Replace a lead with a full object. Any field you leave off is cleared, so this expects the whole record, not just what changed. Reach for lead update unless you specifically want the clearing behaviour.

Takes lead_id as its only positional. --first-name, --email-address and --company-name are required, exactly as on lead create; every other field flag is optional and any you omit is sent as null.

jazzhq-cli lead replace 300 \
  --first-name Ada \
  --email-address ada@example.com \
  --company-name "X Ltd" \
  --job-title "VP Sales"

In that example the lead keeps only the four fields given — a previously stored --city or --phone-number is cleared. Approval state and archiving are untouched either way.

lead archive

Archive a lead, hiding it from listings without deleting it.

jazzhq-cli lead archive 300

Safe to run twice — archiving an already-archived lead succeeds and changes nothing.

lead approve

Approve a lead and convert it into a contact. Prints the lead and the contactId it became.

jazzhq-cli lead approve 300

Safe to retry: approving an already-approved lead returns the same contact rather than creating another. Approving a rejected lead exits 1 with INVALID_STATE_TRANSITION.

lead reject

Reject a lead, optionally recording why.

Argument / Flag	Required	Description
lead_id (positional)	yes	The lead's ID
--comment	no	Reason for the rejection

jazzhq-cli lead reject 300 --comment "No budget this quarter"

Rejecting twice keeps the first comment. Rejecting an approved lead exits 1 with INVALID_STATE_TRANSITION.

Exit codes

Code	Meaning
0	Success
1	API error (e.g. duplicate entry, validation failure) or network error
2	Usage or configuration error (missing arg, missing API key/base URL)

License

MIT