listee-cli

Official command-line interface for Listee — manage authentication, categories, and tasks directly from your terminal via the Listee API (signup, login, logout, status).

Requirements

• Bun 1.2.22 (bun --version)
• Node.js 20+ (runtime for the compiled CLI)
• Listee API base URL (LISTEE_API_URL)

Installation

bun install

Configuration

Create a .env file or export environment variables before running commands:

export LISTEE_API_URL="https://api.your-listee-instance.dev"
# optional: override the Keytar service name
export LISTEE_CLI_KEYCHAIN_SERVICE="listee-cli"

Never commit secrets; the repo defaults to reading from the process environment.

Usage

After building, invoke the CLI via the symlink Bun creates or by running the compiled output.

bun run build
bun run dev              # rebuilds then runs node dist/index.js
listee auth signup --email you@example.com
listee auth login --email you@example.com
listee auth status
listee auth logout
listee categories list [--email you@example.com]
listee categories show <categoryId> [--email you@example.com]
listee categories create --name "Inbox" [--email you@example.com]
listee categories update <categoryId> --name "New name" [--email you@example.com]
listee categories delete <categoryId> [--email you@example.com]
listee tasks list --category <categoryId> [--email you@example.com]
listee tasks create --category <categoryId> --name "Task title" [--description "..."] [--checked] [--email you@example.com]
listee tasks show <taskId> [--email you@example.com]
listee tasks update <taskId> [--name "New title"] [--description "..."] [--clear-description] [--checked|--unchecked] [--email you@example.com]
listee tasks delete <taskId> [--email you@example.com]

listee auth signup starts a temporary local callback server. Leave the command running, open the confirmation email, and the CLI will finish automatically once the browser redirects back to the loopback URL.

Scripts

Command	Description
bun run build	Compile TypeScript to dist/ using project references.
bun run dev	Rebuild and run the CLI for local smoke testing.
bun run lint	Execute Biome (biome.json) in CI mode for consistent styles.
bun test	Run Bun’s built-in test runner.

Project Layout

src/
  index.ts          # CLI entrypoint (Commander wiring)
  commands/auth.ts  # Auth subcommands
  commands/categories.ts
  commands/tasks.ts
  services/auth-service.ts
  services/api-client.ts
  services/category-api.ts
  services/task-api.ts
AGENTS.md           # Agent-specific automation guidelines

Contributing

Human contributors should follow this README plus upcoming CONTRIBUTING.md. Automated coding agents must read AGENTS.md for execution boundaries, tool usage, and reporting format. Align commit messages with Conventional Commits (e.g., feat(auth): add refresh token guard).

Roadmap

• Integrate shared packages from listee-libs once published to npm
• Extend task and category management commands
• Add device code flow support and cohesive CI via listee-ci