cli-inbox-reader

CLI tool that lets AI agents read and write your inBox notes from S3/WebDAV. No MCP, no server, just a command.

Why

inBox is a local-first notes app that syncs via S3 or WebDAV. This CLI gives AI coding agents (Codex, Claude, Cursor etc.) direct access to your notes through simple shell commands — no MCP protocol, no config files to fight with, no app restarts.

Inspired by Agently Mail — the idea that a CLI + Skill is simpler and more reliable than MCP for AI agent integration.

Quick Start

# Install
npm install -g cli-inbox-reader

# Configure (S3 example)
inbox-cli config init \
  --cloud-type s3 \
  --endpoint https://s3.cn-south-1.qiniucs.com \
  --bucket my-bucket \
  --access-key AKID... \
  --secret-key SECRET... \
  --region cn-south-1 \
  --work-dir inBox

# Verify
inbox-cli config test

# Use
inbox-cli list --limit 5
inbox-cli search --query "Flutter"
inbox-cli read --id b10a4576df11401c8673

Commands

| Command | Description | |---------|-------------| | list | List note summaries (with time range and date field filtering) | | read | Read full content of a single note by ID | | search | Search notes by keyword in title/body/tags | | tags | List all tags with usage counts | | create | Create a new note | | update | Partially update an existing note | | delete | Soft-delete a note (requires --confirm) | | config init | Set up cloud storage credentials | | config show | Show current config (secrets masked) | | config test | Test connection to cloud storage |

Config

Config is stored at ~/.inbox-cli/config.json (created by config init). Environment variables (CLOUD_TYPE, S3_ENDPOINT, etc.) work as fallback for compatibility with the MCP version.

Skill for AI Agents

A skill/SKILL.md is included. Install it to your AI agent's skill directory:

# For Codex
cp skill/SKILL.md ~/.codex/skills/inbox-reader/SKILL.md

Once installed, the AI agent will automatically discover the skill and know when to use inbox-cli commands — no MCP, no restart needed.

How it works

AI agent (Codex / Claude / Cursor)
        ↓ exec_command
  inbox-cli (standalone CLI process)
        ↓ S3 ListObjects / WebDAV PROPFIND
  your cloud storage

Each command is a standalone process that connects directly to your S3/WebDAV storage, reads inBox note JSON files, and outputs structured JSON. No persistent server, no protocol handshake, no startup failures to debug.

vs mcp-inbox-reader

| | cli-inbox-reader (CLI + Skill) | mcp-inbox-reader (MCP) | |---|---|---| | Protocol | Plain shell commands | MCP stdio protocol | | Setup | npm install -g + config init | config.toml + app restart | | Activation | Immediate, new session works | Requires app restart | | Failure mode | Clear error message | Silent failure | | Performance | One process per call | Server stays resident with cache |

License

MIT