Commands

All commands are available through the corky CLI.

General

corky --help                    # Show all commands
corky help [FILTER]             # Show command reference (optional filter)
corky init --user EMAIL        # Initialize in current directory
corky init --user EMAIL /path # Initialize at specific path
corky install-skill email     # Install the email agent skill

init

corky init --user EMAIL [PATH] [--provider PROVIDER]
           [--password-cmd CMD] [--labels LABEL,...] [--github-user USER]
           [--name NAME] [--mailbox-name NAME] [--sync] [--force]

Creates {path}/mail/ with directory structure, .corky.toml, and voice.md. If inside a git repo, adds mail to .gitignore. Registers the project dir as a named mailbox in app config.

--provider: gmail (default), protonmail-bridge, imap
--labels: default correspondence (comma-separated)
--force: overwrite existing config
--sync: run sync after init

install-skill

corky install-skill NAME

Install an agent skill into the current directory. Currently supported: email. Mailbox repos ship the skill automatically via mb add/mb reset.

Sync

corky sync                     # Incremental IMAP sync (all accounts)
corky sync full                # Full re-sync (ignore saved state)
corky sync account personal    # Sync one account
corky sync routes              # Apply routing rules to existing conversations
corky sync mailbox [NAME]      # Push/pull shared mailboxes

sync-auth

corky sync-auth

Gmail OAuth setup. Requires credentials.json from Google Cloud Console.

Import

corky sync telegram-import FILE            # Import Telegram Desktop JSON export
corky sync telegram-import DIR             # Import from directory containing result.json
corky sync telegram-import FILE --label personal --account tg-personal

Import Telegram Desktop JSON exports into corky conversations. Each chat becomes a thread with ID tg:{chat_id}. Export from Telegram Desktop: Settings > Advanced > Export Telegram data > JSON format.

Slack

corky slack import FILE.zip                # Import Slack workspace export ZIP
corky slack import FILE.zip --label work --account slack-work

Import Slack workspace export ZIPs. Messages are grouped by thread_ts into threads with ID slack:{channel_id}:{thread_ts}. Export from Slack: Workspace admin > Settings > Import/Export Data > Export.

Both commands support --label (default: provider name) and --account (default: provider name) flags.

Email

corky list-folders [ACCOUNT]   # List IMAP folders for an account
corky add-label LABEL --account NAME         # Add a label to sync config
corky unanswered                             # Find threads awaiting a reply (all scopes)
corky unanswered .                           # Root conversations only
corky unanswered NAME                        # Specific mailbox only

Drafts

corky draft new "Subject" --to EMAIL         # Scaffold a new draft file
corky draft new "Subject" --to EMAIL --mailbox NAME  # Create in mailbox drafts/
corky draft validate                         # Validate all drafts (root + mailboxes)
corky draft validate .                       # Validate root drafts only
corky draft validate NAME                    # Validate drafts in a mailbox
corky draft validate FILE [FILE...]          # Validate specific files
corky draft push mail/drafts/FILE.md         # Save a draft via IMAP
corky draft push mail/drafts/FILE.md --send  # Send via SMTP

draft new

corky draft new SUBJECT --to EMAIL [--cc EMAIL] [--account NAME]
               [--from EMAIL] [--in-reply-to MSG-ID] [--mailbox NAME]

Scaffolds a new draft file with pre-filled metadata. Creates drafts/YYYY-MM-DD-slug.md and prints the path. Author resolved from [owner] name in .corky.toml.

Reply Threading Heuristics

When drafting an email, determine whether to thread as a reply or start a new thread:

User intent	Action
Follow-up, correction, or reply to a recent email	Threaded reply — find the original in `mail/conversations/`, set `in_reply_to` to its Message-ID, derive subject as `Re: <original subject>`
New topic to the same person	New thread — no `in_reply_to`, fresh subject
Ambiguous	Default to reply if there's a recent conversation with the same contact; ask if unclear

Gmail threading requirements:

In-Reply-To and References headers must reference the original Message-ID
Subject must match (adding Re: prefix is fine; changing the subject entirely breaks threading)
Mismatched subjects cause Gmail to create a new thread even with correct headers

draft push

Default: creates a draft via IMAP APPEND to the drafts folder. --send: sends via SMTP. Requires Status to be review or approved. After sending, updates Status to sent.

Account resolution:

**Account** field → match by name in .corky.toml
**From** field → match by email address
Fall back to default account
Credential bubbling: if the draft is inside a mailbox, walk parent directories for a .corky.toml with matching credentials

Contacts

corky contact add NAME --email EMAIL [--email EMAIL2]   # Add a contact manually
corky contact add --from SLUG [NAME]                    # Create from a conversation
corky contact info NAME                                 # Show contact details + threads

corky mailbox add NAME --label LABEL [--name NAME] [--github] [--pat]
corky mailbox sync [NAME]                   # Push/pull shared mailboxes
corky mailbox status                        # Check mailbox status
corky mailbox list                          # List registered mailboxes
corky mailbox remove NAME [--delete-repo]   # Remove a mailbox
corky mailbox rename OLD NEW [--rename-repo] # Rename a mailbox
corky mailbox reset [NAME] [--no-sync]      # Regenerate templates

All mailbox commands accept the mb alias (e.g. corky mb add).

Watch

corky watch                    # Poll IMAP and sync on an interval
corky watch --interval 60      # Override poll interval (seconds)

Global flags

corky --mailbox NAME <command>  # Use a specific mailbox for any command

Development

corky audit-docs               # Audit instruction files for staleness

Corky