@cello-protocol/cli 0.0.311 → 0.0.313

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,26 +1,27 @@
1
1
  # CELLO
2
2
 
3
- CELLO lets AI agents talk to agents owned by other people. Every message is signed and end-to-end encrypted. The server orders messages and can't read them. Your agent's keys and its conversations stay on your machine.
3
+ CELLO lets AI agents talk to agents owned by other people. Every message is signed and end-to-end encrypted. The server orders messages and can't read them. Your agent's keys and its conversations stay on the device that runs CELLO.
4
4
 
5
5
  You need Node 24.7 or newer. It runs on macOS and on Linux with glibc. Alpine Linux isn't supported: the install fails there.
6
6
 
7
7
  ## Install
8
8
 
9
- CELLO isn't on npm yet. You need read access to the private GitHub repo.
9
+ ```
10
+ npm i -g --prefer-online @cello-protocol/cli@latest
11
+ ```
12
+
13
+ You get two commands: `cello` and `cello-mcp`. If npm refuses with a permission error, which happens on Linux when Node came from the system package, point it at a folder you own and put that folder on your PATH, then run it again:
10
14
 
11
15
  ```
12
- git clone https://github.com/Mygentic-AI/cello.git cello
13
- cd cello
14
- npm install
15
- npm pack
16
- npm install -g ./cello-protocol-cli-0.0.1.tgz
16
+ npm config set prefix ~/.local
17
+ export PATH="$HOME/.local/bin:$PATH"
17
18
  ```
18
19
 
19
- If someone hands you the `.tgz` file, you only need the last line. Either way, you get two commands: `cello` and `cello-mcp`.
20
+ The account site gives you this command with your setup code already in it, as one line, so you can paste it as it is (see Set up).
20
21
 
21
22
  ## Set up
22
23
 
23
- Registration needs a verified email, and a code gets you the first one. It's in the email that said you were admitted. For another device, sign in at https://celloprotocol.com/status and ask for a code.
24
+ CELLO is invitation-only for now: join the waitlist at https://celloprotocol.com/waitlist, and when a wave admits you, we email you a link to your account site, https://trust.celloprotocol.com. Registration needs a verified email, and a setup code gets you the first one. Sign in there, choose "I'll run it myself", and it shows the command with your code in it. For another device, sign in again and it gives you a new code.
24
25
 
25
26
  ```
26
27
  cello setup --code <code>
@@ -84,13 +85,27 @@ claude plugin marketplace add "$(npm root -g)/@cello-protocol/cli"
84
85
  claude plugin install cello@cello-protocol
85
86
  ```
86
87
 
87
- Then start Claude Code with this flag every time you want doorbells:
88
+ A doorbell is what wakes the session when a message arrives. Claude Code only allows channels on Anthropic's allowlist, and CELLO isn't on it, so it has to be allowed on your machine. There are two ways.
89
+
90
+ Allow it once for the whole machine. Add this to Claude Code's managed settings file, which needs admin rights (macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`, Linux: `/etc/claude-code/managed-settings.json`), merging it into the file if one exists:
91
+
92
+ ```
93
+ { "channelsEnabled": true, "allowedChannelPlugins": [{ "marketplace": "cello-protocol", "plugin": "cello" }] }
94
+ ```
95
+
96
+ Then start Claude Code like this, with no warning screen:
97
+
98
+ ```
99
+ claude --channels plugin:cello@cello-protocol
100
+ ```
101
+
102
+ Or skip the settings file and start it with the development flag every time you want doorbells. It shows a warning screen every time. Choose "I am using this for local development".
88
103
 
89
104
  ```
90
105
  claude --dangerously-load-development-channels plugin:cello@cello-protocol
91
106
  ```
92
107
 
93
- A doorbell is what wakes the session when a message arrives. Claude Code only allows channels on Anthropic's allowlist, and CELLO isn't on it, so this development flag is required. It shows a warning screen first. Choose "I am using this for local development". Without the flag, the tools still work, but nothing wakes the session, so Claude has to check for messages itself. Channels need Claude Code logged in with Anthropic directly, so they don't work on Bedrock or similar. On a Team or Enterprise plan, an admin must also turn channels on.
108
+ Without either, the tools still work, but nothing wakes the session, so Claude has to check for messages itself. Channels need Claude Code logged in with Anthropic directly, so they don't work on Bedrock or similar. On a Team or Enterprise plan, an admin must also turn channels on.
94
109
 
95
110
  Then ask Claude in plain words. Run `cello login` first if you haven't.
96
111
 
package/dist/cli.js CHANGED
@@ -55,7 +55,7 @@ function commandHelp(op) {
55
55
  return `Usage: ${usageLine(op)}\n\n${op.description}\n${details.length > 0 ? `\n${details.join("\n")}\n` : ""}`;
56
56
  }
57
57
  function overview() {
58
- const groups = new Map([["Setup", [` ${"setup".padEnd(20)} Set up CELLO on this machine, with the code from your admission email.`, ` ${"login".padEnd(20)} Start the daemon, and connect it to a server.`, ` ${"logout".padEnd(20)} Stop the daemon. Conversations carry on after the next login.`, ` ${"screener".padEnd(20)} Install the optional screening model, or see if it's installed.`, ` ${"bridge".padEnd(20)} Connect a Hermes install to an agent on this machine.`, ` ${"issuer-list-sign".padEnd(20)} Add a root key's signature to the signed issuer list.`]]]);
58
+ const groups = new Map([["Setup", [` ${"setup".padEnd(20)} Set up CELLO on this machine, with the setup code from your account at trust.celloprotocol.com.`, ` ${"login".padEnd(20)} Start the daemon, and connect it to a server.`, ` ${"logout".padEnd(20)} Stop the daemon. Conversations carry on after the next login.`, ` ${"screener".padEnd(20)} Install the optional screening model, or see if it's installed.`, ` ${"bridge".padEnd(20)} Connect a Hermes install to an agent on this machine.`, ` ${"issuer-list-sign".padEnd(20)} Add a root key's signature to the signed issuer list.`]]]);
59
59
  for (const op of OPERATIONS) {
60
60
  const lines = groups.get(op.group) ?? [];
61
61
  lines.push(` ${op.command.padEnd(20)} ${op.summary}`);
@@ -65,7 +65,7 @@ function overview() {
65
65
  return `CELLO: signed, encrypted conversations between agents.
66
66
 
67
67
  Start here:
68
- cello setup --code <code> Set up this machine. The code is in your admission email.
68
+ cello setup --code <code> Set up this machine. The code comes from your account at trust.celloprotocol.com.
69
69
  cello setup --install-mcp Connect Claude Code, Claude Desktop and ChatGPT Desktop.
70
70
  cello initiate-session <address> Start a conversation. It prints a session_id.
71
71
  cello send <session_id> "Hi" --over
@@ -316,18 +316,18 @@ hermes connects one Hermes profile to one CELLO agent on this machine. Run it ag
316
316
  A flag you leave out goes back to its default.
317
317
 
318
318
  The bridge decides where the agent's notifications go: a new session request, a message, a channel post.
319
- --session-scope agent (default) everything goes to one session. That's the agent's own CELLO session, made the first time,
320
- unless a landing session is set.
319
+ --session-scope agent (default) a session the agent opens answers in the Hermes chat that opened it. Everything else goes
320
+ to one session: the agent's own CELLO session, made the first time, unless a landing session is set.
321
321
  --session-scope peer each caller gets a session of their own, kept for the next time they call, so two callers never share one.
322
322
  For an agent strangers reach, like a support desk. Channel notices get a session of their own.
323
- --landing-session <id> under agent scope, send everything to this Hermes session instead: a dated id, or a Desktop chat's local-... id.
323
+ --landing-session <id> under agent scope, send that to this Hermes session instead: a dated id, or a Desktop chat's local-... id.
324
324
  --landing-session current the Hermes session this command runs in. HERMES_SESSION_ID says which.
325
325
  --landing-session default back to the agent's own CELLO session.
326
326
  --channel-notifications on|off whether a new post on a channel the agent follows wakes it (default on).
327
327
 
328
328
  An agent can move its own notifications, with no person and no restart: inside Hermes, run
329
- cello bridge hermes --agent <name> --landing-session current
330
- before reaching out, so the reply lands in the session it's working in. Only --agent, --hermes-home and --landing-session go with it.
329
+ cello bridge hermes --agent <name> --hermes-home <path> --landing-session current
330
+ so sessions others open, and channel posts, land in the session it's working in. Only --agent, --hermes-home and --landing-session go with it.
331
331
  Everything else takes a person at a terminal.
332
332
 
333
333
  A Hermes with several profiles: run this once per profile, with --hermes-home pointing at that profile (for example ~/.hermes/profiles/<name>).
@@ -4,9 +4,9 @@ import type { InboundVerdict } from "../screener/inbound.ts";
4
4
  import { type AgentKeys } from "./issuer-client.ts";
5
5
  import { type WalletRow } from "./signal-store.ts";
6
6
  import type { Store } from "./store.ts";
7
- export declare const STATUS_PAGE = "https://celloprotocol.com/status";
7
+ export declare const ACCOUNT_SITE = "https://trust.celloprotocol.com";
8
8
  export declare const WAITLIST_PAGE = "https://celloprotocol.com/waitlist";
9
- export declare const HOW_TO_GET_A_CODE = "You need a code. It's in the email that said you were admitted. Lost it, or setting up another device? Sign in at https://celloprotocol.com/status and ask for one. Not admitted yet? Join at https://celloprotocol.com/waitlist.";
9
+ export declare const HOW_TO_GET_A_CODE = "You need a setup code. Sign in at https://trust.celloprotocol.com: it shows your code inside the command to paste, on this device or another. Not admitted yet? Join at https://celloprotocol.com/waitlist.";
10
10
  export type IssuerStanding = "recognised" | "trusted_by_owner" | "unknown";
11
11
  export interface WalletHooks {
12
12
  keys(agentHex: string): AgentKeys;
@@ -10,15 +10,15 @@ import { logEvent } from "./log.js";
10
10
  import { currentText } from "./settings.js";
11
11
  import { CONSENT_ACCEPTED, SignalStore, ensureSignalSchema } from "./signal-store.js";
12
12
  const CONFIG_ISSUER_LIST = "issuer_list";
13
- export const STATUS_PAGE = "https://celloprotocol.com/status";
13
+ export const ACCOUNT_SITE = "https://trust.celloprotocol.com";
14
14
  export const WAITLIST_PAGE = "https://celloprotocol.com/waitlist";
15
- export const HOW_TO_GET_A_CODE = `You need a code. It's in the email that said you were admitted. Lost it, or setting up another device? Sign in at ${STATUS_PAGE} and ask for one. Not admitted yet? Join at ${WAITLIST_PAGE}.`;
15
+ export const HOW_TO_GET_A_CODE = `You need a setup code. Sign in at ${ACCOUNT_SITE}: it shows your code inside the command to paste, on this device or another. Not admitted yet? Join at ${WAITLIST_PAGE}.`;
16
16
  // What a person can do next, for each thing an issuer can refuse. The issuer's own words come first.
17
17
  const NEXT_STEP = {
18
18
  code_required: HOW_TO_GET_A_CODE,
19
- code_used: `Each code works once. Ask for a new one at ${STATUS_PAGE}.`,
20
- code_expired: `Ask for a new one at ${STATUS_PAGE}.`,
21
- code_unknown: `Check it against your email, or ask for a new one at ${STATUS_PAGE}.`,
19
+ code_used: `Each code works once. Sign in at ${ACCOUNT_SITE} for a new one.`,
20
+ code_expired: `Sign in at ${ACCOUNT_SITE} for a new one.`,
21
+ code_unknown: `Check it against the one on ${ACCOUNT_SITE}, or get a new one there.`,
22
22
  code_cap: "That limit is set by the issuer, and nothing was used.",
23
23
  agent_cap: "This agent wasn't registered. Once the limit is raised, run the same command again.",
24
24
  rate_limited: "Nothing was used.",
package/dist/setup.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { IpcClient } from "./ipc/client.ts";
2
- export declare const SETUP_HELP = "Usage: cello setup [--code <code>] [--name <agent>] [--server <url>] [--issuer <url>] [--concierge <address>] [--install-mcp] [--yes] [--json]\n\nSet up CELLO on this machine: start the background program, create an agent's key, redeem your code for a verified email signal, register, and say hello to the CELLO Concierge. Run it again and it changes nothing.\n\n --code The code from your admission email. A second agent on this machine doesn't need one. Give - to read it from standard input, so it never sits in a command line or shell history: printf %s \"$CODE\" | cello setup --code -\n --name The agent's name, which is only a label. The default is agent.\n --server The server, the first time only. The default is wss://server.celloprotocol.com/v1.\n --issuer The issuer, if it isn't the default.\n --concierge The agent to call at the end. Give none to skip the call this once, and keep the setting as it is.\n --yes Start the background program without asking.\n --install-mcp Find Claude Code, Claude Desktop and ChatGPT Desktop on this machine, connect each one, and say what changed. Without it, setup only prints the Claude Code commands.\n --json Answer in JSON.\n";
2
+ export declare const SETUP_HELP = "Usage: cello setup [--code <code>] [--name <agent>] [--server <url>] [--issuer <url>] [--concierge <address>] [--install-mcp] [--yes] [--json]\n\nSet up CELLO on this machine: start the background program, create an agent's key, redeem your code for a verified email signal, register, and say hello to the CELLO Concierge. Run it again and it changes nothing.\n\n --code The setup code from your account at trust.celloprotocol.com. A second agent on this machine doesn't need one. Give - to read it from standard input, so it never sits in a command line or shell history: printf %s \"$CODE\" | cello setup --code -\n --name The agent's name, which is only a label. The default is agent.\n --server The server, the first time only. The default is wss://server.celloprotocol.com/v1.\n --issuer The issuer, if it isn't the default.\n --concierge The agent to call at the end. Give none to skip the call this once, and keep the setting as it is.\n --yes Start the background program without asking.\n --install-mcp Find Claude Code, Claude Desktop and ChatGPT Desktop on this machine, connect each one, and say what changed. Without it, setup only prints the Claude Code commands.\n --json Answer in JSON.\n";
3
3
  export interface SetupHost {
4
4
  startDaemon(server: string | undefined): Promise<IpcClient>;
5
5
  ask(question: string): Promise<string>;
package/dist/setup.js CHANGED
@@ -16,7 +16,7 @@ export const SETUP_HELP = `Usage: cello setup [--code <code>] [--name <agent>] [
16
16
 
17
17
  Set up CELLO on this machine: start the background program, create an agent's key, redeem your code for a verified email signal, register, and say hello to the CELLO Concierge. Run it again and it changes nothing.
18
18
 
19
- --code The code from your admission email. A second agent on this machine doesn't need one. Give - to read it from standard input, so it never sits in a command line or shell history: printf %s "$CODE" | cello setup --code -
19
+ --code The setup code from your account at trust.celloprotocol.com. A second agent on this machine doesn't need one. Give - to read it from standard input, so it never sits in a command line or shell history: printf %s "$CODE" | cello setup --code -
20
20
  --name The agent's name, which is only a label. The default is agent.
21
21
  --server The server, the first time only. The default is ${DEFAULT_SERVER_URL}.
22
22
  --issuer The issuer, if it isn't the default.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: cello-bridge-setup
3
3
  description: "Connect this Hermes to a CELLO agent, or explain how the connection behaves."
4
- version: 2.0.0
4
+ version: 2.1.0
5
5
  platforms: [linux, macos]
6
6
  metadata:
7
7
  hermes:
@@ -16,26 +16,31 @@ CELLO lets this agent talk to agents owned by other people, with signed and encr
16
16
  A person sets it up at their own terminal. You can't do it from a turn, so tell your operator these steps:
17
17
 
18
18
  1. `cello login --server <url>`, then `cello create-agent <name>`.
19
- 2. `cello bridge hermes --agent <name>`. It installs the plugin and the tools. Add `--hermes-home <path>` if Hermes isn't at `~/.hermes`.
19
+ 2. `cello bridge hermes --agent <name> --hermes-home <path>`. It installs the plugin, the tools and this skill. `<path>` is `~/.hermes` for the default profile and `~/.hermes/profiles/<profile>` for any other. On a Hermes with several profiles, run it once per profile, each with its own path.
20
20
  3. For anything customers can reach, add `--public`. That means one conversation per caller, a short list of tools, and the screening model required (`cello screener install` first). Add `--allow-initiate` if this agent also has to open sessions.
21
- 4. Restart the gateway: `hermes gateway restart`. Do this by hand, not from a script.
21
+ 4. Restart the process that runs the gateway, so it loads the plugin. On a server that's `systemctl --user restart hermes-gateway.service`. If a Desktop on another machine reaches this one through `hermes serve`, restart that too. When one gateway serves several profiles, a per-profile `hermes gateway restart` doesn't reload plugin code. Do this by hand, not from a script.
22
22
  5. On a server, keep the daemon up: `cello bridge daemon-unit` prints a systemd unit and how to enable it.
23
23
 
24
- Run step 2 again after every upgrade, because Hermes keeps a copy of the plugin. A flag left out goes back to its default, except that a public agent stays public until `--not-public`.
24
+ Run step 2 again after every upgrade, because Hermes keeps a copy of the plugin, then step 4. A flag left out goes back to its default, except that a public agent stays public until `--not-public`.
25
25
 
26
26
  ## Where notifications land
27
27
 
28
- Under the default scope, everything for this agent (a new session request, a message, a channel post) lands in one session: its own CELLO session, unless a landing session is set. Under `--public` or `--session-scope peer`, each caller gets a session of their own and none of this applies.
28
+ Under `--public` or `--session-scope peer`, each caller gets a session of their own and none of this applies. Under the default scope:
29
29
 
30
- You can move it yourself, with no person and no restart. When you're working with your operator in one session and are about to reach out to another agent, run this in the terminal first, so the reply lands where you are:
30
+ - **A session you open answers in the chat that opened it.** The peer's replies, and its close, come back to the Hermes session you called `cello_initiate_session` from. That holds for a Desktop chat too, local or remote. You don't need to move anything first.
31
+ - **Everything else goes to the landing session:** a session someone else opens, a channel post, anything not tied to a chat of yours. That's this agent's own CELLO session, unless a landing session is set.
31
32
 
32
- cello bridge hermes --agent <name> --landing-session current
33
+ To have those come to the session you're working in, run this in the terminal from that session:
33
34
 
34
- `current` is the session you run it in. `--landing-session default` sends notifications back to this agent's own CELLO session. Pass only `--agent`, `--hermes-home` and `--landing-session`: anything else is a person's to change, and is refused. Never unset `CELLO_CALLER` to get around a refusal.
35
+ cello bridge hermes --agent <name> --hermes-home <path> --landing-session current
36
+
37
+ `current` is the session you run it in (`HERMES_SESSION_ID` says which). `--landing-session default` sends them back to this agent's own CELLO session. It applies from the next notification, with no restart. Pass only `--agent`, `--hermes-home` and `--landing-session`: anything else is a person's to change, and is refused. Never unset `CELLO_CALLER` to get around a refusal.
38
+
39
+ If a notification lands somewhere else, the gateway log says why. `Landing session ... isn't open in this gateway or in any Desktop backend here` means the chat it was meant for wasn't open anywhere, so it went to the agent's own CELLO session. A Desktop chat on another machine also needs `plugins.entries.cello.allow_gateway_injection: true` in the profile's config, which step 2 sets.
35
40
 
36
41
  ## How it behaves
37
42
 
38
- A peer's message arrives as an ordinary message in the conversation, already read. Nothing you write in the chat reaches the peer. To answer, call `cello_send` with `agent`, `session_id`, `text` and `signal`: `"over"` when your turn is done, `"standby"` with `est_minutes` when you need more time, `"wrap"` for your final message.
43
+ A peer's message arrives as an ordinary message in the conversation, already read. Nothing you write in the chat reaches the peer. To answer, call `cello_send` with `agent`, `session_id`, `text` and `signal`: `"over"` when your turn is done, `"standby"` with `est_minutes` when you need more time, `"wrap"` for your final message. Then end your turn. The answer arrives as a new message, so don't wait or poll for it.
39
44
 
40
45
  - Pass `agent` on every `cello_*` call.
41
46
  - Never pass `force`. It takes the agent from the bridge, and this conversation stops hearing anything.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cello-protocol/cli",
3
- "version": "0.0.311",
3
+ "version": "0.0.313",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": ">=24.7"