cli-workspace

Monorepo workspace for CLI tools built with Clean Architecture (Ports & Adapters). Each CLI wraps a desktop app or web API through shell-friendly verbs, JSON output, and a consistent option grammar.

CLIs

Tool	Binary	Target	Install
zotero-cli	zt	Zotero Web API v3 + Local API	npm i -g @beomsukoh/zotero-cli
devonthink-cli	dt	DEVONthink scripting dictionary	npm i -g devonthink-cli
eagle-cli	eg	Eagle local HTTP API	npm i -g @beomsukoh/eagle-cli

# Zotero: search your library
zt search "machine learning" --limit 5

# DEVONthink: import a file
dt add ~/Downloads/paper.pdf --db "01. Personal" --at "/Projects"

# Eagle: import an image from URL
eg import:url --url https://example.com/photo.png --name "Reference"

Setup

git clone --recurse-submodules https://github.com/GoBeromsu/cli-workspace.git
cd cli-workspace

Each CLI is an independent git submodule — build and test them individually:

cd zotero-cli && pnpm install && pnpm check && pnpm test && pnpm build
cd eagle-cli && pnpm install && pnpm check && pnpm test && pnpm build

Architecture

All CLIs follow the same 4-layer Clean Architecture:

commands/        → Parse CLI args, dispatch to application layer
application/     → Port interfaces, types, error hierarchy (pure, no deps)
adapters/        → Port implementations (HTTP, JXA, console)
infrastructure/  → Low-level utilities (HTTP client, process runner)

Key principles:

• Independence: Each CLI is a standalone repository. No knowledge of the workspace.
• Zero runtime deps: Only devDependencies (TypeScript, tsx, vitest).
• CommandModule pattern: Every command has parse() (pure) and execute() (async).
• Port/Adapter: Business logic depends on interfaces, not implementations.

See cli-boiler-template/ for the shared code template.

Workspace Structure

cli-workspace/
├── .claude/
│   ├── agents/              # Agent team definitions (developer, researcher, qa)
│   ├── knowledge/           # Architecture pattern docs
│   └── settings.json
├── cli-boiler-template/     # Shared code template (source of truth)
├── zotero-cli/              # Submodule: Zotero CLI
├── devonthink cli/          # Submodule: DEVONthink CLI
├── eagle-cli/               # Submodule: Eagle CLI
├── CLAUDE.md
├── AGENTS.md                # Team configuration
└── README.md

Agent Team

Agent	Role	Model
cli-developer	Implementation (commands, adapters, infrastructure)	sonnet
cli-researcher	API docs, type definitions, specs	sonnet
cli-qa	Tests, code review, architecture compliance	opus

Creating a New CLI

1. Copy cli-boiler-template/ to a new directory
2. Update package.json (name, bin, description)
3. Define your port interface in application/ports.ts
4. Implement the HTTP/JXA adapter
5. Add commands, wire in compositionRoot.ts
6. Verify: pnpm check && pnpm test && pnpm build
7. Add as submodule: git submodule add <url> <dir>

License

MIT