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
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@

Notable changes to `@wirecat/amo-cli`. One section per version, newest first.

## 0.1.1 — 18.11.2026

### Fixed

- Published from GitHub Actions with npm provenance, so WireCat Desktop installs it: Desktop refuses a built-in tool's
release that its own repository's workflow did not build, and 0.1.0 was published from a computer.
- The user docs match bitrix24-cli's: MCP and permissions pages, a full start page, `amo <profile> setup` in the
README's quick start, environment variables in the configuration page, and more troubleshooting rows.

## 0.1.0 — 17.11.2026

### Added
Expand Down
72 changes: 40 additions & 32 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,29 +66,30 @@ Agent: (runs amo work deals move deal:12 "Negotiation")

How it compares with other amoCRM and Kommo tools and MCP servers:
[the comparison](https://wirecat.dev/en/docs/amo/compare). Another tool fits better when an agent should set tasks
and write notes by itself. In `amo` that takes `api call` at a terminal, after you allow it.
and write notes by itself. In `amo` that takes `api call`, which you run yourself after you allow it.

## Quick start

An account administrator first makes one private integration in amoCRM or Kommo. Its token is the key `amo` signs in
with. [Install and connect](docs/installation.md) shows each click.

Then find your account's address, the one you open the CRM at. The commands below use the example
`https://example.amocrm.ru`. Put your own address in its place.

```sh
npm install -g @wirecat/amo-cli
amo skill install # the agent skill, for Claude Code, Codex and Gemini CLI
amo work session start --host https://example.amocrm.ru # paste the token when asked, it goes to the keyring
amo work sync # copy your deals and their clients
amo skill install # the agent skill, for Claude Code, Codex, Gemini CLI and OpenClaw
amo work setup # make a private integration in amoCRM or Kommo, paste its token
amo work sync # copy your deals and their clients
amo work deals list status:open
```

`work` is a profile, a name you choose for this account. It is the first word of every command that uses the
account. An address can also end in `.kommo.com` or `.amocrm.com`. You need Node.js 22.16 or a later 22.x, or
Node.js 24 or later. `amo doctor` shows what is set up and needs no network.
`work` is a profile, a name you choose for one account. It is the first word of every command that uses the account,
and none is ever assumed. `amo work setup` shows each click in amoCRM or Kommo, asks for the account's address and the
integration's long-lived token, checks them against the account and keeps the token in the system keyring. An account
administrator makes the integration once. A sync copies the deals assigned to the user the token belongs to. To copy
a colleague's too, see
[which deals sync copies](https://github.com/WireCatLabs/amo-cli/blob/main/docs/configuration.md#which-deals-sync-copies).

More: [install and connect](docs/installation.md), with the browser sign-in and WireCat Desktop.
You need Node.js 22.16 or a later 22.x, or Node.js 24 or later. `amo doctor` needs no network and shows what is set
up.

More: [install and connect](https://github.com/WireCatLabs/amo-cli/blob/main/docs/installation.md), with the browser
sign-in through the integration.

## Use it with your agent

Expand All @@ -108,10 +109,12 @@ amo work mcp add claude-code --allow-writes # or: codex
amo work mcp config # the entry for Claude Desktop, Cursor and others
```

Over MCP nobody is at a terminal to answer a question, so a write set to `ask` goes ahead. Before an agent gets the
profile over MCP, set the writes it must not make to `readonly` or `deny`, or turn on approval in the agent's client.
Text from the account reaches the agent marked as untrusted, so the agent reads it as data, never as instructions.
`api call` and the sign-in commands are not offered over MCP.

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

## What it can do

Expand All @@ -127,7 +130,7 @@ amo work deals close deal:12 lost --reason "Example: chose another supplier"
Create and update deals with the CRM's own fields by their labels. `--dry-run` shows what a change would do and the
permissions it checks.

More: [use it](docs/usage.md#read-your-deals)
More: [use it](https://github.com/WireCatLabs/amo-cli/blob/main/docs/usage.md#read-your-deals)

### Contacts and companies

Expand All @@ -150,7 +153,7 @@ amo work schedule command crm-digest --at 08:30 -- changes list --format report
Tasks, comments and calls are copied once you turn on the activities setting. The digest goes to a desktop notice,
or to Telegram or a mailbox through your own WireCat `tg` or `mail`.

More: [tasks and the digest](docs/usage.md#tasks-and-what-changed)
More: [tasks and the digest](https://github.com/WireCatLabs/amo-cli/blob/main/docs/usage.md#tasks-and-what-changed)

### Any API operation

Expand All @@ -161,7 +164,7 @@ amo work api call "GET /api/v4/leads" --params '{"limit":5}'

Every operation of amoCRM's API v4 reference can be called, each checked against its own permission.

More: [call the API](docs/usage.md#call-the-api)
More: [call the API](https://github.com/WireCatLabs/amo-cli/blob/main/docs/usage.md#call-the-api)

### With your other sources

Expand All @@ -184,7 +187,7 @@ More: [WireCat](https://wirecat.dev)
unknown, so you check the record first.
- **Made for scripts.** `--json` prints one JSON value, and every error has a code to branch on.

More: [command reference](docs/commands.md)
More: [command reference](https://github.com/WireCatLabs/amo-cli/blob/main/docs/commands.md)

## Settings and permissions

Expand All @@ -196,18 +199,20 @@ clients, Salesbots, webhooks, writing tasks and giving a record to another user
amo work config set permissions.deals.close deny # this profile closes no deal
```

Over MCP nobody is there to answer, so `ask` lets the write go ahead. Set a key to `readonly` or `deny` to stop an
agent.
A stage change can start the account's own automation, such as a Salesbot that writes to a client. If your account
has one, decide who may move a deal before an agent gets the profile.

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

## Limits

- `amo` is tested against a fake account built from the Kommo API reference, and each release passes a check on a
live test account: it syncs, reads, and creates, moves and closes a deal.
- amoCRM has no call that deletes a deal, so there is no `deals delete`.
- Without amoCRM's paid API filter add-on, `sync` reads a contact or company one request at a time, and a contact
list cannot be narrowed by owner or time. A search by words still works.
- amoCRM's API v4 has no call that deletes a deal, so there is no `deals delete`. Close the deal as lost instead.
- Files on deals and contacts are not supported yet.
- Without amoCRM's paid API filter add-on, `sync` reads a contact or company one request at a time, and a live list
of contacts or companies cannot be narrowed by owner or time. A search by words still works.
- The Chats API, Drive and amoCRM's AI agent API live on other hosts, and `amo` does not reach them.
- Before 1.0, a minor version may change commands, `--json` fields and MCP tools. The changelog marks each such
change.
Expand All @@ -218,7 +223,8 @@ The token works like a password: anyone who has it can do what its administrator
keyring and never prints it. amoCRM has no call that revokes a token, so after a leak revoke it in the integration
itself.

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

## When something goes wrong

Expand All @@ -227,24 +233,26 @@ amo doctor # what is set up, without connecting
amo work session status --check # whether the sign-in works, and as whom
```

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

## Documentation

Everything is on [wirecat.dev/en/docs/amo](https://wirecat.dev/en/docs/amo). The same pages are in
[docs/](docs/index.md).
[docs/](https://github.com/WireCatLabs/amo-cli/blob/main/docs/index.md).

## Development

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 run against a fake account built from the Kommo API reference, with invented records and an injected keyring.
Nothing reaches a real account. `pnpm release:check` runs every check a release needs.

More: [testing](docs/dev/TESTING.md) · [design](docs/dev/DESIGN.md)
More: [testing](https://github.com/WireCatLabs/amo-cli/blob/main/docs/dev/TESTING.md) · [design](https://github.com/WireCatLabs/amo-cli/blob/main/docs/dev/DESIGN.md)

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

Expand All @@ -255,4 +263,4 @@ agents your context from messengers, mail, calendars, documents and CRMs. Each o

## License

[Apache 2.0](LICENSE)
[Apache 2.0](https://github.com/WireCatLabs/amo-cli/blob/main/LICENSE)
60 changes: 26 additions & 34 deletions docs/configuration.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Settings

Decide what your AI agent may do in your amoCRM or Kommo account before you hand it over. Read only, change deals but
never message a client, or ask you first: each profile keeps its own answer.
Change how `amo` works for one account, or for every account on this computer, with one command, and see where each
value came from. You change only the few that matter to you, and the rest keep their defaults.

An agent then works inside the limits you set. It reads and moves deals where you allow it, and a write you denied
stops before any request reaches the account. The same settings decide which deals `sync` copies and whether tasks
and calls come with them.
You decide whose deals `sync` copies, whether tasks and calls come with them, which stages open a task on your
computer, and what an agent may do. Only you can loosen a permission or change what a sync copies: an agent that
tries is refused.

Settings live in one file, `config.json`, in the folder `amo doctor` shows. Each profile has its own part, and
`defaults` apply to every profile. `amo work config show` lists each setting and where it came from: the file, a
Expand All @@ -19,6 +19,7 @@ variable or the default.
4. [Tasks and calls](#tasks-and-calls)
5. [A task when a deal enters a stage](#a-task-when-a-deal-enters-a-stage)
6. [Run records](#run-records)
7. [Variables](#variables)

## See and change a setting

Expand All @@ -31,34 +32,13 @@ amo work config unset limit
## Permissions

`permissions` decides what a command may do for this profile: `allow`, `ask`, `readonly` or `deny`, per permission
key. Each command has a key, such as `deals.close`, and so does each operation of the amoCRM API. An operation's key is
the path's words and the verb: `GET /api/v4/leads/{id}` is `api.leads.id.get`, so `api.leads` covers every operation
on deals.
key. Over MCP `ask` does not ask: the write goes ahead. The keys, their built-in levels and how to keep an agent's
writes yours are on [Permissions](permissions.md).

```sh
amo work config set permissions.deals.close deny
```

What a new profile allows:

- **Allowed:** what `amo`'s own commands read, such as deals, contacts, companies, pipelines, fields, users, tasks and
events, and creating and changing deals, contacts and companies.
- **Asks first:** every other read, such as notes or unsorted, other writes, and every delete.
- **Denied, reads too:** conversations, chats, Salesbots, webhooks, widgets, website buttons, calls, and switching users
on or off.
- **Denied writes:** adding users, and writing tasks, roles and lead sources. `crm.assign-others` is denied too, so no
write gives a deal, a task or a contact to another user.

`api call` also checks the key of the command that does the same thing, such as `deals.update` for
`PATCH /api/v4/leads`, so a raw call cannot get round a command's level.

Some things only the account's administrator does through `amo`, whatever the permissions say: deleting, setting a
field to nothing, unlinking records, and reading contacts, companies, notes and events through `api call`.

Over MCP there is no one to ask, so `ask` lets the command run. Set a key to `readonly` or `deny` to stop an agent.
`amo work mcp serve --permission deals.close=deny` makes a key stricter for one server only, and never looser.
`AMO_READ_ONLY=1` refuses every write, whatever the permissions say.

## Which deals sync copies

By default `sync` copies the deals assigned to the signed-in user. An administrator can choose other users instead.
Expand All @@ -71,14 +51,14 @@ amo work config set crm.amocrm:example.amocrm.ru.unassigned 7001,7002
amo work sync
```

You set this yourself at a terminal, since an agent's run is refused it. A user who is not an administrator can choose only themselves. No setting copies the whole CRM. Any other client is
read live with `people` or `organizations`.
Only you set this, since an agent's run is refused it. A user who is not an administrator can choose only
themselves. No setting copies the whole CRM. Any other client is read live with `people` or `organizations`.

## Tasks and calls

`crm.amocrm:<address>.activities` is off by default. Turned on, the next `sync` copies the tasks, comments and calls on
your deals and their clients from the last 90 days. [Tasks and what changed](usage.md#tasks-and-what-changed) shows the
command. Like the choice of deals, only you set it, at a terminal.
command. Like the choice of deals, only you set it.

## A task when a deal enters a stage

Expand All @@ -96,12 +76,24 @@ amo work sync
```

`amo` reads the account's stage history, so a deal that passed through a stage between two syncs still gets that
stage's task. Moves made before the setting was first set open none. Only you set it, at a terminal. To stop,
stage's task. Moves made before the setting was first set open none. Only you set it. To stop,
`amo work config unset crm.amocrm:example.amocrm.ru.stage-tasks`.

## Run records

A command that fails is kept as a run, for `amo runs list` and `runs show`. `api call` and `session status --check`
are kept when they succeed too, unless `record` is `false` (then only failures) or they ran with `--no-record`.
`record_input` decides whether a run keeps the words you typed. It is `true` unless you set it to `false`. Secrets are
masked either way, as [security](security.md) shows.
`record_input` decides whether a run keeps the words you typed: `true` (the default), `false`, or `failed` for failed
runs only. Secrets are masked either way, as [security](security.md) shows.

## Variables

A variable set for one shell or one timer comes before the file:

- `AMO_PROFILE` names the profile, so a command can leave it out.
- `AMO_READ_ONLY=1` refuses every write, whatever the permissions say.
- `AMO_TOKEN` with `AMO_HOST` signs in with a long-lived token for that run only, without the keyring. `AMO_HOST` is
the account's address, and `AMO_TOKEN` without it is an error.
- `AMO_AMOCRM_CLIENT_SECRET` gives the integration's secret key to `session start --client-id`.
- `AMO_CONFIG_DIR` and `AMO_STATE_DIR` move the settings and the state to other folders. A sign-in made with them is
kept apart from your usual one.
1 change: 1 addition & 0 deletions docs/dev/live-checks.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@
0.0.0 fb5e08895f6b5215c77511f29b9080888537e76d 2026-11-17 bin/amo-live v2:3a2b7d0ef004497001db523f40a1bdf84cd7003c03d1dd851dc218e5b6d5faa3
0.1.0 54897c6d7a69136530f10c835b57e0784b516f02 2026-11-17 bin/amo-live v2:b99af01f37903e7644a805ce029cd81d1103163ebb3de82acbe906a90e4a7b19
0.1.0 d6bfe3d1d4b1c4754e271575448eb9a6947ed804 2026-11-17 bin/amo-live v2:2fd2d0dee7b910d9ea018559a5fedb49f71a87f6d5913b41a58694ecdb0555b5
0.1.1 266bdea805d3d10e9b71a38dac193c098e80da53 2026-11-17 bin/amo-live v2:20275c533be085ded04c495661a44579a4456385334744e05bd91679bdb5cb41
Loading
Loading