Metadata-Version: 2.4
Name: agent-tool-close-crm-cli
Version: 0.2.1
Summary: Agent-ready command-line interface for Close CRM — set up leads, keep contacts and notes current, track tasks and opportunities, and search across all of it. Installs the `close` command.
Author: Zierhut IT, Alexander Zierhut
License: MIT
Project-URL: Homepage, https://github.com/alexander-zierhut/agent-tool-close-crm-cli
Project-URL: Repository, https://github.com/alexander-zierhut/agent-tool-close-crm-cli
Project-URL: Issues, https://github.com/alexander-zierhut/agent-tool-close-crm-cli/issues
Project-URL: Changelog, https://github.com/alexander-zierhut/agent-tool-close-crm-cli/releases
Keywords: close,close-crm,crm,sales,leads,contacts,opportunities,pipeline,sales-pipeline,cli,command-line,close-api,ai-agent,llm,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Customer Service
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agent-tool-shared-cli<0.2,>=0.1.4
Requires-Dist: typer>=0.12
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25
Requires-Dist: rich>=13
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-timeout>=2.3; extra == "test"
Provides-Extra: build
Requires-Dist: pyinstaller>=6; extra == "build"
Dynamic: license-file

# close — the agent-ready Close CRM CLI

> Set up leads, keep contacts and notes current, track tasks and opportunities,
> and search across all of it — a [Close](https://www.close.com) CRM client an
> LLM can drive with no prior knowledge of it.

[![PyPI](https://img.shields.io/pypi/v/agent-tool-close-crm-cli)](https://pypi.org/project/agent-tool-close-crm-cli/)
[![CI](https://github.com/alexander-zierhut/agent-tool-close-crm-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/alexander-zierhut/agent-tool-close-crm-cli/actions/workflows/ci.yml)
![Python](https://img.shields.io/pypi/pyversions/agent-tool-close-crm-cli)
![License: MIT](https://img.shields.io/badge/license-MIT-green)
![Agent ready](https://img.shields.io/badge/agent-ready-blue)

**Install:** `pipx install agent-tool-close-crm-cli` — then run `close guide`.

`close` wraps the [Close CRM REST API](https://developer.close.com/) in a command
line built for **AI agents**: JSON on stdout by default, errors as JSON on stderr
with a meaningful exit code, a built-in `guide` that needs no network, and
`--dry-run` on every write. Point an agent at a website and let it stand a lead
up end to end — company, contacts, notes, a first task and an opportunity — then
keep it current, search across everything, and see what happened last.

## The command surface

```text
 Usage: close [OPTIONS] COMMAND [ARGS]...

 Agent-friendly CLI for Close CRM: set up leads, keep contacts current, log notes
 and calls, create and reschedule tasks and opportunities, and search across all of
 it.

 Output is JSON on stdout by default (errors are JSON on stderr with a non-zero
 exit code); add `-o table` or trim with `--fields id,name`.

 New here / no context? Run `close guide` for the full playbook.

╭─ Options ────────────────────────────────────────────────────────────────────────╮
│ --output            -o      <json|table|markdown|csv>  Output format: json       │
│                                                        (default), table,         │
│                                                        markdown, csv. Also       │
│                                                        --format/-f, anywhere on  │
│                                                        the line.                 │
│ --fields,--columns          <str>                      Comma-separated fields to │
│                                                        return, e.g.              │
│                                                        'id,display_name'. Works  │
│                                                        anywhere on the line.     │
│ --profile           -p      <str>                      Configuration profile.    │
│                                                        One profile per Close API │
│                                                        key (e.g. a second org).  │
│ --dry-run                                              Mutating commands: print  │
│                                                        the request that would be │
│                                                        sent and exit.            │
│ --stream                                               Stream results as NDJSON. │
│ --no-context                                           Ignore the saved session  │
│                                                        context for this command. │
│ --no-color                                             Disable coloured output.  │
│ --version           -V                                 Show version and exit.    │
│ --help                                                 Show this message and     │
│                                                        exit.                     │
╰──────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────╮
│ guide        Built-in operating guide — how to use this CLI without external     │
│ report       Report a bug / missing feature — repo + pre-filled issue link.      │
│              docs.                                                               │
│ lead         Leads (accounts): create, read, search, update, set status.         │
│ status       Discover the org's lead and opportunity statuses.                   │
│ contact      Contacts (people at a lead): add, update, list.                     │
│ activity     Timeline: log notes, document calls, see what happened last.        │
│ task         Tasks: create, see what's open, reschedule, complete.               │
│ opportunity  Opportunities (deals): set up, list, move close dates, win/lose.    │
│ search       Clever search across leads, contacts, opportunities and tasks.      │
│ auth         Log in with an API key, log out, inspect credentials.               │
│ raw          Escape hatch: call any Close API endpoint directly.                 │
│ settings     View & change CLI settings.                                         │
│ context      Sticky session defaults (e.g. a lead), applied to later commands.   │
│ install      Integrate with other tools (e.g. `install claude`).                 │
╰──────────────────────────────────────────────────────────────────────────────────╯

 Learn more:  `close guide`  ·  `close guide <topic>`  ·  `close <group> --help`
```

> Typed, name-resolving commands cover **leads**, **contacts**, **activities**
> (notes & calls), **tasks**, **opportunities**, **statuses** and **search** —
> pass a name, not an id (`--lead "Acme Inc"`, `-s Qualified`), and preview any
> write with `--dry-run`. `close raw` still reaches anything not yet wrapped. Run
> `close guide` for the full map.

## Quickstart

```bash
pipx install agent-tool-close-crm-cli
close auth login                       # paste an API key from app.close.com/settings/api/
# ...or run headless, no config file:
export CLOSE_API_KEY=api_xxxxxxxx

close guide                            # the built-in manual — no network needed

# stand a whole account up from a website:
close lead create -n "Acme Inc" --url https://acme.com -s Qualified
close contact add --lead "Acme Inc" -n "Jane Doe" --title CTO --email jane@acme.com
close activity note "Inbound from the website form." --lead "Acme Inc"
close task create "Book a demo" --lead "Acme Inc" --due +3d
close opportunity create --lead "Acme Inc" --value 5000 -s "Demo Completed" --close +4w

# then keep it moving:
close activity recent --lead "Acme Inc"    # what happened last on this account
close task list --overdue                  # what's slipping
close opportunity reminders --within 14d   # deals closing soon
close search leads 'status:"Qualified"'    # clever search
```

## Why "agent-ready"

An agent-ready CLI is one an LLM with **no prior knowledge** of the tool can
discover, drive correctly, and know whether it worked — without a human in the
loop. Concretely:

- **stdout is JSON, always.** `close … | jq` never breaks; human status goes to stderr.
- **Errors are a machine channel too.** `{"error": "...", "status": 404}` on stderr,
  and a 422 carries `fieldErrors` — the exact fields Close rejected, as dotted
  paths (`contacts.0.emails.0.email`) — so a rejected write is fixable on the next call.
- **Exit codes are the error taxonomy** (see below): branch on the class without parsing prose.
- **It teaches itself.** `close guide` is a zero-config, zero-network, offline
  manual compiled into the binary; `close install claude` registers it as a Claude Code skill.
- **Preview before you write.** `--dry-run` prints the exact request and sends nothing.

## The Close data model

| Object | Id prefix | What |
|---|---|---|
| **Lead** | `lead_` | A company/account — the central object; everything hangs off it. Has a status. |
| **Contact** | `cont_` | A person at a lead — names, emails, phones. |
| **Activity** | `acti_` | The lead's timeline: notes, calls, emails, SMS, status changes. "What happened last." |
| **Task** | `task_` | A to-do with a due date. "Open tasks" = incomplete ones due. |
| **Opportunity** | `oppo_` | A potential deal: value, confidence, a pipeline status (active/won/lost), a close date. |
| **Status** | `stat_` | Lead & opportunity statuses — **per-org and custom**; resolve them, never hard-code. |

Lists return `{"data": [...], "has_more": ..., "total_results": N}`; page with
`_skip`/`_limit` (max 100). Updates are **PUT** (partial — send only what changed).

## Output contract & exit codes

Default output is JSON on stdout; add `-o table` for humans, `-o csv` to export,
`--fields id,display_name` to trim, `--stream` for NDJSON. Errors are JSON on
stderr with a non-zero exit code:

| Code | Meaning | | Code | Meaning |
|---|---|---|---|---|
| 0 | success (incl. a `--dry-run`) | | 5 | not found |
| 1 | generic error | | 6 | conflict |
| 3 | config (no API key) | | 7 | validation — see `fieldErrors` |
| 4 | auth (bad/insufficient key) | | 130 | interrupted |

Codes 0–7 mean the same thing across every tool in the family.

## Authentication

A Close **API key** (starts with `api_`), minted at
[app.close.com/settings/api/](https://app.close.com/settings/api/). The key *is*
the org selector — there is no server URL to configure.

```bash
close auth login                       # prompts, verifies against /me/, stores in your OS keyring
export CLOSE_API_KEY=api_xxxxxxxx      # or headless, no config file
close auth status                      # names WHICH key/backend is actually in use
```

Precedence is **env > OS keyring > 0600 file**; a second Close org is a second
profile (`close auth login --profile client-x`).

## Part of the family

`close` is built on **[agent-tool-shared-cli](https://github.com/alexander-zierhut/agent-tool-shared-cli)**,
the shared chassis that fixes the output format, the exit-code taxonomy and the
credential handling — so an agent that has learned one tool in the family already
knows the next.

| Tool | Install | For |
| --- | --- | --- |
| [**close**](https://github.com/alexander-zierhut/agent-tool-close-crm-cli) | `pipx install agent-tool-close-crm-cli` | Close CRM — leads, contacts, notes, tasks, opportunities, search |
| [**drone-cli**](https://github.com/alexander-zierhut/agent-tool-drone-cli) | `pipx install agent-tool-drone-cli` | Drone CI — builds, failing-step logs, promotions |
| [**grafana**](https://github.com/alexander-zierhut/agent-tool-grafana-cli) | `pipx install agent-tool-grafana-cli` | Grafana — log discovery, health scan, alert routing |
| [**openproject**](https://github.com/alexander-zierhut/agent-tool-openproject-cli) | `pipx install agent-tool-openproject-cli` | OpenProject — work packages, time, invoicing |
| [**lexware-office**](https://github.com/alexander-zierhut/agent-tool-lexware-office-cli) | `pipx install agent-tool-lexware-office-cli` | Lexware Office — invoices, contacts, AR-aging |

**Keywords:** Close CRM CLI, Close.com API, sales CRM command line, leads,
contacts, sales opportunities, sales pipeline, tasks, CRM automation, AI agent
tool, LLM tooling, Claude.

## License

MIT — see [LICENSE](LICENSE).
