Skip to content

README.md

Latest commit

 

History

History
170 lines (111 loc) · 4.85 KB

README.md

File metadata and controls

170 lines (111 loc) · 4.85 KB
Raw

Replies CLI

A small, dependency-free CLI for retrieving Replies todos, threads, messages, comments, replies, and attachments. It is designed for people, scripts, and shell-capable AI agents.

Requirements

Node.js 22.18 or newer. The bundled JavaScript runtime has no dependencies or build step.

Zero-install usage

Any shell-capable agent can run the CLI directly from GitHub:

npx --yes --allow-git=root github:replies/replies-cli todo download 1498901

npm 12 disables Git packages by default, so --allow-git=root permits this explicitly requested package without permitting transitive Git dependencies.

In sandboxes or other environments that provide HTTP_PROXY or HTTPS_PROXY, enable Node's environment-proxy support:

NODE_USE_ENV_PROXY=1 \
  npx --yes --allow-git=root github:replies/replies-cli todo download 1498901

The same setting applies to an installed command:

NODE_USE_ENV_PROXY=1 replies-cli todo download 1498901

For a persistent replies-cli command:

npm install --global github:replies/replies-cli

Pi

Install the package once:

pi install git:github.com/replies/replies-cli

Pi discovers the bundled Replies skill and runs its bundled CLI. A separate clone, symlink, or global npm installation is not required.

Claude Code

Add this repository as a marketplace and install its plugin from within Claude Code:

/plugin marketplace add replies/replies-cli
/plugin install replies@replies-cli

Claude Code discovers the bundled Replies skill. A separate global CLI installation is not required.

For local plugin development:

claude --plugin-dir ./replies-cli

Authentication

Generate a personal API key in Replies account settings and provide it through the environment:

export REPLIES_API_TOKEN='...'

Never put the token in a URL, command argument, GitHub issue, or log.

ID-based commands use https://1.replies.io by default. Set a different Replies origin when needed:

export REPLIES_HOST='https://example.replies.io'

REPLIES_HOST must be an HTTPS Replies origin without a path. Supplying a Replies web or API URL to todo get or todo download infers its origin instead.

Usage

Use get to write one canonical JSON resource to stdout:

replies-cli todo get 1498901
replies-cli todo-threads get 1498901
replies-cli thread-messages get 12345
replies-cli thread-replies get 12345
replies-cli get 'https://1.replies.io/api/v1/todos/1498901'

Use todo download to recursively download the todo, todo-thread metadata, every thread's messages and replies, and every linked attachment:

replies-cli todo download 1498901 --output ./todo-1498901

The todo argument may instead be a Replies web or API URL. Its origin is used for every linked request:

replies-cli todo download 'https://1.replies.io/#97/todos/1498901' --output ./todo-1498901

Without --output, the CLI creates a safe temporary directory. A named output directory must not already exist unless --resume is supplied:

replies-cli todo download 1498901 --output ./todo-1498901 --resume

The download uses bounded concurrency and writes one compact final receipt. Independent failures are recorded in manifest.json; the command finishes the remaining work and exits non-zero when the result is incomplete. A resumed download skips files marked complete in the manifest.

The output is shallow and keeps canonical API responses unchanged:

todo-1498901/
├── manifest.json
├── todo-1498901.json
├── todo-1498901-threads.json
├── thread-12345-messages.json
├── thread-12345-replies.json
└── attachments/
    └── a81c42f0c51921e7-screenshot.png

Attachment names always have a deterministic prefix derived from their content URL, followed by the original safe filename. The manifest maps files to source URLs and parent comments, messages, or replies and records sizes and SHA-256 checksums.

Download an individual attachment and receive guidance for inspecting the saved file with the agent's available tools:

replies-cli attachment download 'https://1.replies.io/api/v1/attachments/team-97/...?name=screenshot.png'

An optional --output works for individual attachments.

Help for people:

replies-cli --help

Compact machine-readable help for agents:

replies-cli --help --agent

get responses larger than 1 MiB are saved to a temporary JSON file. The CLI prints a small JSON object containing its savedTo path.

For security, the token is sent only to HTTPS URLs under replies.io/api/v1, and redirects are not followed. Download manifests and receipts never contain the token.

Development

Run the dependency-free tests with:

npm test

Validate the Claude Code plugin when Claude Code is installed:

claude plugin validate .

License

MIT