CLI Reference

The Duet CLI gives you full control over your notes, todos, and agents from the terminal. It connects directly to your PostgreSQL database - no API server required.

Installation

npm install -g @noteduet/cli

Verify the installation:

duet --version

Environment

export DUET_DATABASE_URL="postgresql://user:pass@localhost:5432/duet_dev"

Note Commands

duet note add [content]

Create a new note. Content can be provided as an argument or piped from stdin.

# Create a note with title and tags
duet note add "Buy groceries" -t "Shopping List" --tag personal

# Pipe content from a file
cat meeting-notes.md | duet note add -t "Standup Notes"

duet note list

List all notes, newest first.

# List all notes by Claude
duet note list --by agent:claude

# List notes with a specific tag
duet note list --tag engineering --limit 10

duet note view <id>

View a note's full content and metadata including title, author, tags, and timestamps.

duet note view abc123

duet note edit <id>

Edit an existing note. A new version is created automatically.

duet note edit abc123 -t "Updated Title" -c "New content here"

duet note search <query>

Full-text search across all notes using PostgreSQL's search engine.

duet note search "deployment checklist" --limit 5

duet note archive <id>

Archive a note. The note is hidden from default views but not permanently deleted.

duet note archive abc123

duet note unarchive <id>

Restore an archived note back to the active notes list.

duet note unarchive abc123

duet note delete <id>

Permanently delete a note. This action is irreversible and requires the -f flag.

duet note delete abc123 --force

duet note history <id>

Show the version history of a note, including who made each change and when.

duet note history abc123

Todo Commands

duet todo add <title>

Create a new todo.

# Create a high-priority todo with a due date
duet todo add "Review PR #42" -p high --due 2026-03-20T17:00:00Z

# Create a todo linked to a note
duet todo add "Follow up on meeting action items" --note-id abc123

duet todo list

List todos with optional filters.

# List all pending high-priority todos
duet todo list -s pending -p high

# List todos due this week
duet todo list --due-before 2026-03-23T00:00:00Z

duet todo done <id>

Mark a todo as complete.

duet todo done abc123

duet todo update <id>

Update an existing todo.

duet todo update abc123 -p urgent --due 2026-03-19T12:00:00Z

duet todo delete <id>

Permanently delete a todo. Requires the -f flag.

duet todo delete abc123 --force

Agent Commands

duet agent add <name>

Register a new agent and receive an API key. The key is only displayed once.

# Register an agent with default permissions
duet agent add claude

# Register a read-only agent
duet agent add monitor --permissions read

duet agent list

List all registered agents with their status and permissions.

duet agent list

duet agent deactivate <id>

Temporarily deactivate an agent. The agent's API key will stop working until reactivated.

duet agent deactivate abc123

duet agent reactivate <id>

Reactivate a previously deactivated agent.

duet agent reactivate abc123

duet agent delete <id>

Permanently delete an agent. Requires the -f flag.

duet agent delete abc123 --force

Activity Command

duet activity

View the activity feed showing recent actions by all users and agents.

# View recent activity by Claude
duet activity --actor claude --limit 10

# View all note-related activity
duet activity --type note

Server Command

duet serve

Start the Duet API server. This is useful for running the web UI alongside the CLI.

# Start on default port
duet serve

# Start on a custom port
duet serve -p 3000

Tips

• Use --json on any list command to pipe output into jq for further processing.
• Set DUET_DATABASE_URL in your shell profile so you don't have to provide it every time.
• Deletion commands (delete) always require -f/--force to prevent accidental data loss.
• The CLI connects directly to PostgreSQL, so it works without a running Duet server.