Metadata-Version: 2.4
Name: jazzhq-cli
Version: 0.3.0
Summary: Command-line tool for managing customer and partner data using the JazzHQ APIs
Author-email: vijayaraj <vijay@jazzhq.ai>
License-Expression: MIT
Project-URL: Homepage, https://jazzhq.ai
Keywords: jazzhq,saas22,partners,cli,api
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# jazzhq-cli

Command-line tool for managing customer and partner data using the [JazzHQ](https://jazzhq.ai) APIs.

## Install

```bash
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:

```bash
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:

```bash
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` |

```bash
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.

```bash
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 |

```bash
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 |

```bash
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.

```bash
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:

```bash
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` |

```bash
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 |

```bash
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 |

```bash
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 |

```bash
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`.

```bash
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.

```bash
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.

```bash
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.

```bash
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 |

```bash
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
