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