Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 1 addition & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,4 @@ Notable changes to `@wirecat/attio-cli`. One section per version, newest first.

### Added

- Started from `@wirecat/cli-template` 0.28.0, built from one file, `wirecat.config.ts`.
- **`attio <profile> sync` copies your Attio people and companies into WireCat's local store**, with each
attribute's current value only. Attio cannot list what changed since a time, so each sync lists every record.
- **`attio <profile> session start` signs in with an Attio access token** from stdin, checked against `GET /v2/self`.
- **`attio <profile> api` runs every operation of the Attio API**, each with its own flags, help and `--json`.
- Started from `@wirecat/cli-template` 0.28.0.
240 changes: 208 additions & 32 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,73 +1,249 @@
# attio: Attio CLI for AI agents
# attio: Attio CRM CLI and MCP server for AI agents

Your Attio people and companies in WireCat's local store, searchable next to your messages, mail and meetings. One
tool for you and for Claude Code, Codex or any agent that speaks MCP.
<p align="center">
Know where every deal stands without opening Attio. Ask Claude, ChatGPT, Codex or any AI agent, and it answers from
a copy of your Attio deals on your computer, even offline.
</p>

<p align="center">
<a href="https://github.com/WireCatLabs/attio-cli/blob/main/docs/index.md">Docs</a> ·
<a href="https://github.com/WireCatLabs/attio-cli/blob/main/docs/installation.md">Install</a> ·
<a href="https://github.com/WireCatLabs/attio-cli/blob/main/docs/usage.md">Usage</a>
<a href="https://github.com/WireCatLabs/attio-cli/blob/main/docs/usage.md">Usage</a> ·
<a href="https://discord.gg/DebENqbRrJ">Discord</a>
</p>

<p align="center">
<a href="https://www.npmjs.com/package/@wirecat/attio-cli"><img src="https://img.shields.io/npm/v/@wirecat/attio-cli" alt="npm"></a>
<a href="https://github.com/WireCatLabs/attio-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache 2.0"></a>
</p>

- **Every operation of the Attio API is a command.** `attio api list` shows them, each with its own
flags, help and `--json`.
- **Your agent gets the same commands as tools.** An MCP server and an agent skill come with it, no second codebase.
- **You decide what it may change.** Each profile allows, asks or denies each command, and a delete needs a key of
its own.
- **Ask instead of clicking.** "Which deals are stuck in Negotiation?" gets an answer in a second, in Claude Code,
Codex, Claude Desktop or any app that speaks MCP.
- **Your pipeline, offline.** Deals, stages and what changed since yesterday are read from your computer, with no
request to Attio.
- **Safe to hand to an agent.** The deal commands only read, and one line keeps every write in the Attio API away
from an agent.

## What you get

Ask your agent about Attio. It finds the right command with `attio commands --json`, runs it, and answers
from the result. A command it may not run stops with a clear refusal before anything reaches Attio.
- **The answer, not the search.** Ask about a deal in your own words. The agent finds it with its stage, amount,
company and people.
- **The pipeline at a glance.** How many deals stand in each stage, their total per currency, and your win rate.
- **What changed overnight.** Deals created, moved, won and lost, as a list or a short morning digest.
- **People and companies on demand.** Read live from Attio, with e-mails and phones, when you ask.
- **Attio deals export.** Any list of deals, people or companies becomes a CSV file for a spreadsheet.

```text
You: Which deals are in Negotiation?
Agent: (runs attio work deals list stage:Negotiation status:open)
· "Example LLC renewal", 24 000 USD, owner Anna Example
· "Sample Inc pilot", 6 500 USD, owner Bob Sample
You: What did we win this week?
Agent: (runs attio work changes list change:won "at>=7d")
One deal: "Example Corp expansion", 12 000 USD, won on Tuesday.
```

*Invented deals, illustrative output.*

## Why attio

- The token stays in the system keyring, and every command names the profile it uses.
- Every operation is tested against a strict fake built from the API description, in `src/api.test.ts`.
- `--dry-run` shows what a write would send, and sends nothing.
- **A copy of your CRM on your computer.** `sync` copies your deals, people and companies into a local store. Lists,
the pipeline board and search answer from it with no request to Attio, also offline.
- **A permission on every action.** Each command and each Attio API operation has its own level: allow, ask, read
only or deny. `WCATTIO_READ_ONLY=1` stops every write.
- **The token stays in your system keyring.** It never appears in output, errors or run records, and is never taken
as an argument.
- **Your CRM beside your other context.** Deals sit in the same local store as your messages, mail, notes and
meetings from the other WireCat tools, so one search covers all of them.
- **The whole Attio API too.** Every operation is a command with its own help, for what has no command of its own
yet: notes, tasks, lists, custom objects.
- **Free and open source.** Apache 2.0.

## Quick start

In [WireCat Desktop](https://wirecat.dev), add Attio from the tool list and paste the access token when it asks. Or in
a terminal:

```sh
pnpm install
pnpm build
node dist/bin/attio.js doctor
npm install -g @wirecat/attio-cli
attio skill install # the agent skill, for Claude Code, Codex, Gemini CLI and OpenClaw
attio work session start # paste your Attio access token
attio work sync # copy your deals, people and companies
attio work deals list status:open
```

Once it is on npm: `npm install -g @wirecat/attio-cli`, then `attio doctor`. Every command that uses an account
starts with a profile, a name you choose: `attio personal config show`.
`work` is a profile, a name you choose for one Attio workspace. It is the first word of every command that uses an
account, and none is ever assumed.

Sign in once with `attio personal session start`. It asks for the token and keeps it in the keyring.
**The access token.** In Attio, open Workspace settings → Developers → New access token. Give it read access to
`record_permission`, `object_configuration` and `user_management`, and copy it. Only a workspace admin can make one.
`session start` asks for it without showing it, checks it with Attio and keeps it in the system keyring.

You need Node.js 22.16 or a later 22.x, or Node.js 24 or later. `attio doctor` needs no network and shows what is set
up.

More: [installation and sign-in, step by step](https://github.com/WireCatLabs/attio-cli/blob/main/docs/installation.md)

## Use it with your agent

Ask in plain words. The agent picks the commands.

> *"Use attio. What changed in our pipeline since yesterday?"*
> *"Use attio. How many deals did we win in the last 30 days, and what is our win rate?"*
> *"Use attio. Who is our contact at Example LLC, and what deals do we have open with them?"*

- **Claude Code, Codex, Gemini CLI** and other agents with a terminal run `attio` themselves. `attio skill install`
teaches them how.
- **Claude Desktop, Cursor** and other MCP apps connect to the Attio MCP server, `attio work mcp serve`.
- **ChatGPT or Claude in the browser** reach it through your own tunnel, after a login with a one-time code.

```sh
attio personal mcp add claude-code
attio skill install
attio work config set permissions.api readonly # no writes through the Attio API on this profile
attio work mcp add claude-code --allow-writes # or: codex
attio work mcp config # the entry for Claude Desktop, Cursor and others
```

`attio personal mcp check` shows the tools your agent gets. `attio personal mcp config` prints the setup for any
other MCP client.
Over MCP nobody is at a terminal to answer a question, so a write set to `ask` goes ahead. The first line above keeps
every write away from the agent.

More: [agents and MCP](https://github.com/WireCatLabs/attio-cli/blob/main/docs/mcp.md) ·
[permissions](https://github.com/WireCatLabs/attio-cli/blob/main/docs/permissions.md)

## What it can do

[docs/commands.md](docs/commands.md) lists every command, and `--help` after any of them shows its flags.
### Deals

```sh
attio work deals list status:open
attio work deals list stage:"In Progress"
attio work deals show deal:12 # one deal with its company and people
attio work deals list status:open --format csv > deals.csv
```

Won is the stage Attio celebrates, and lost is a stage whose title starts with "Lost".

### The pipeline

```sh
attio work pipelines show # each stage: how many, their sum, how many went on
attio work pipelines show --since-time 30d # the deals made in the last 30 days, with the win rate
```

### What changed

```sh
attio work changes list "at>=1d" # deals created, moved, won and lost
attio work changes list "at>=1d" --format report # the same as a short morning digest
```

### People, companies and members

```sh
attio work people list anna # search Attio by name or e-mail
attio work organizations list example # companies by name
attio work users list # your workspace members
```

These read Attio itself, so they need the network.

### Your own attributes and search

```sh
attio work fields list deals # the attributes your workspace added, with their type
attio work search all "Example LLC" # deals next to your messages, notes and meetings
```

### Any Attio API operation

```sh
attio work api list # every operation, without calling Attio
attio work api objects-list # the objects in your workspace
```

More: [using attio](https://github.com/WireCatLabs/attio-cli/blob/main/docs/usage.md) ·
[every command](https://github.com/WireCatLabs/attio-cli/blob/main/docs/commands.md)

## How it works

- **An access token.** A workspace admin makes it in Attio. It is kept in the system keyring, or in a private file
on a computer without one.
- **A local copy.** `sync` copies the workspace's deals, people and companies, with the stages of Attio's deal
pipeline, into the WireCat local store. Attio cannot list only what changed, so each sync reads every record.
- **Live where it matters.** `people`, `organizations` and `users` ask Attio each time, so they show the newest data.
- **Made for scripts.** `--json` prints one JSON value for every command, and an error comes as JSON with a code to
branch on.

## Settings and permissions

`attio personal config show` prints the profile's settings. See [docs/configuration.md](docs/configuration.md).
Each profile has a level for every command and every Attio API operation: `allow`, `ask`, `readonly` or `deny`. A
delete through the API asks first at a terminal.

```sh
attio work config set permissions.api readonly # the Attio API reads, never writes
attio work config show # each setting and where it came from
```

More: [permissions](https://github.com/WireCatLabs/attio-cli/blob/main/docs/permissions.md) ·
[settings](https://github.com/WireCatLabs/attio-cli/blob/main/docs/configuration.md)

## Limits

- The deal commands read. Moving or closing a deal from `attio` is on the
[roadmap](https://github.com/WireCatLabs/attio-cli/blob/main/docs/roadmap.md), and so are notes, tasks, custom
objects, lists and a one-click sign-in.
- Only a workspace admin can make the token, and it reads the whole workspace.
- Attio documents 100 reads and 25 writes a second
([rate limits](https://docs.attio.com/rest-api/guides/rate-limiting)).
- Before 1.0, a minor version may change commands, `--json` fields and MCP tools. The changelog lists each such
change under "may break callers".

## Security

See [docs/security.md](docs/security.md), and [SECURITY.md](SECURITY.md) to report a problem.
The token reads your whole workspace, so `attio` keeps it in the system keyring and never prints it, in output,
errors or run records. It talks only to `api.attio.com`. Text from Attio is marked as untrusted, so an agent reads a
deal title as data, not as an instruction.

More: [security](https://github.com/WireCatLabs/attio-cli/blob/main/docs/security.md) · Report a vulnerability:
[SECURITY.md](https://github.com/WireCatLabs/attio-cli/blob/main/SECURITY.md)

## When something goes wrong

Run `attio doctor` and see [docs/troubleshooting.md](docs/troubleshooting.md). Report a bug on
[GitHub](https://github.com/WireCatLabs/attio-cli/issues).
```sh
attio doctor # what is set up, without connecting
attio work session status --check # asks Attio which workspace the token belongs to
```

More: [troubleshooting](https://github.com/WireCatLabs/attio-cli/blob/main/docs/troubleshooting.md) · Ask on
[Discord](https://discord.gg/DebENqbRrJ) · Bugs go to this repository's
[issues](https://github.com/WireCatLabs/attio-cli/issues).

## Documentation

Everything is in [docs/](https://github.com/WireCatLabs/attio-cli/blob/main/docs/index.md): installation, usage, MCP,
permissions, settings, the command reference and the roadmap.

## Development

Started from [cli-template](https://github.com/WireCatLabs/cli-template). Its design is in
[docs/dev/DESIGN.md](docs/dev/DESIGN.md), and the working rules are in [AGENTS.md](AGENTS.md). Published as
[@wirecat/attio-cli](https://www.npmjs.com/package/@wirecat/attio-cli).
You need Node.js 22.16 or a later 22.x, or Node.js 24 or later, and pnpm.

```sh
pnpm install && pnpm test
```

Tests use a fake Attio built from Attio's API description, with invented records, and nothing reaches a real
workspace. The CLI is described in one file, `wirecat.config.ts`, and started from
[cli-template](https://github.com/WireCatLabs/cli-template).

More: [design](https://github.com/WireCatLabs/attio-cli/blob/main/docs/dev/DESIGN.md) ·
[working rules](https://github.com/WireCatLabs/attio-cli/blob/main/AGENTS.md)

Pull requests, bug reports and ideas go to [issues](https://github.com/WireCatLabs/attio-cli/issues).

## Part of WireCat

`attio` is one of the [WireCat](https://wirecat.dev) tools: open-source, local-first command-line tools that give AI
agents your context from messengers, mail, calendars, CRMs and documents. Each one works on its own.

## License

[Apache 2.0](https://github.com/WireCatLabs/attio-cli/blob/main/LICENSE)
13 changes: 13 additions & 0 deletions changes/feat-attio-source.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
### Added

- Built from one file, `wirecat.config.ts`.
- **`attio <profile> sync` copies your Attio deals into WireCat's local store**, with their stage, owner, amount,
company, people and the workspace's own attributes, and your people and companies. Attio cannot list what
changed since a time, so each sync lists every record.
- **`attio <profile> deals`, `pipelines`, `changes`, `fields` and `search all` read the copy**, offline too. Attio's
one deal pipeline is `Deals`: a stage Attio celebrates is won, one titled "Lost" is lost.
- **`attio <profile> people list|show` and `organizations list|show` read Attio live**, words searching names and
emails.
- **`attio <profile> session start` signs in with an Attio access token** from stdin, checked against `GET /v2/self`.
- **`attio <profile> api` runs every operation of the Attio API**, each with its own flags, help and `--json`.
- **`attio <profile> users list|show` reads your workspace members live.**
3 changes: 2 additions & 1 deletion contracts/help.snap
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
attio — Attio CRM: people and companies, searchable with your other WireCat data
attio — Attio CRM: deals, people and companies for you and your AI agent

Usage: attio <profile> <command> [options]
Account commands start with your profile, a name you choose; none is ever assumed.
Expand All @@ -15,6 +15,7 @@ Works with:
b24 Bitrix24 CRM: deals, leads and pipelines, searchable with your other WireCat data
pbx Asterisk PBX calls and recordings, searchable with your other WireCat data
notion Notion pages and databases as local text, searchable with your other WireCat data
ydisk Yandex Disk folders as local text, searchable with your other WireCat data

Next: attio commands every command, by section
attio help options output, offline, timeouts, dry run
Expand Down
6 changes: 3 additions & 3 deletions contracts/mcp-catalogue.json
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
"api attributes-statuses-update": "write",
"api objects-records-query": "read",
"api objects-records-create": "write",
"api objects-records-assert": "write",
"api objects-records-upsert": "write",
"api objects-records-get": "read",
"api objects-records-replace": "write",
"api objects-records-update": "write",
Expand All @@ -40,7 +40,7 @@
"api objects-records-search": "read",
"api activities-records-query": "read",
"api activities-records-create": "write",
"api activities-records-assert": "write",
"api activities-records-upsert": "write",
"api activities-records-get": "read",
"api activities-records-replace": "write",
"api activities-records-update": "write",
Expand All @@ -57,7 +57,7 @@
"api lists-views-delete": "write",
"api lists-entries-query": "read",
"api lists-entries-create": "write",
"api lists-entries-assert": "write",
"api lists-entries-upsert": "write",
"api lists-entries-get": "read",
"api lists-entries-replace": "write",
"api lists-entries-update": "write",
Expand Down
Loading
Loading