CLI & MCP server

Install

Taskessa ships as prebuilt binaries. Nothing to compile: download the build for your platform, unzip it, and put taskessa and taskessa-mcp on your PATH.

macOS / Linux: move both binaries into a directory on your PATH (~/.local/bin, for example) and make them executable with chmod +x.
Windows: add the folder holding taskessa.exe and taskessa-mcp.exe to your PATH.

Check that it works:

taskessa --version

Authenticate

Nothing to configure: taskessa connects to your Taskessa account on its own.

taskessa auth login      # asks for your email, then a hidden password
taskessa auth status     # account, API URL and session status
taskessa auth logout     # clears the cached session (--purge also drops the password)

auth login checks your credentials, unlocks your key locally (then releases it), stores your password in the OS keychain, caches a session token, and remembers your account so later commands need no flags. Your password is read from a no-echo prompt, never from a command argument, and your key is re-derived on every run without ever touching the disk.

Use the CLI

Content always comes in through stdin, never through command arguments. Decrypted output goes to stdout; counts and diagnostics go to stderr. A failed decrypt prints <undecryptable> and exits with code 7, never a silent gap.

# read (content decrypted locally)
taskessa task list --all --json
taskessa habit list
taskessa calendar list --start 2026-06-01 --end 2026-06-07
taskessa planning today

# write (content from stdin, never a command argument)
echo "Buy oat milk" | taskessa task add --priority High
taskessa task done <id>

Connect your own LLM (MCP)

Start the stdio MCP server with taskessa mcp (identical to the taskessa-mcp binary). It exposes read and write tools across tasks, subtasks, relations, comments, attachments, projects, sections, workflow states, labels, habits, categories, check-ins and calendar blocks, plus sharing, agent management, local search and account export. A write returns a dry-run preview until you pass `confirm=true`, and anything that changes who can read your data always requires it. Four capabilities stay out of the MCP on purpose and remain command line only: sealing an agent's full-access key, deleting your account, importing an export, and local maintenance.

Claude Desktop

Store your password in the OS keychain once:

[email protected] TASKESSA_PASSWORD='…' taskessa-mcp store-password

Then add this to claude_desktop_config.json. No secret lands in the file: it comes from the keychain.

{
  "mcpServers": {
    "taskessa": {
      "command": "taskessa-mcp",
      "args": [],
      "env": {
        "TASKESSA_EMAIL": "[email protected]"
      }
    }
  }
}

If Claude Desktop cannot find taskessa-mcp on its PATH, use the absolute path (the output of which taskessa-mcp). Restart Claude Desktop and the Taskessa tools show up in the client.

Configuration

Variable	Default	Purpose
`TASKESSA_EMAIL`	—	Account email. The CLI also asks for it and remembers it.
`TASKESSA_PASSWORD`	—	Password fallback for scripts. Prefer the keychain or the prompt.

Zero-knowledge guarantees

Content is encrypted on your device. The server stores ciphertext plus plaintext metadata, and no code path reads what you wrote.
Your encryption key is derived from your password locally and is never escrowed. A one-time recovery key gives you access back if you forget your password.
Lose both your password and your recovery key and your content is gone for good. That is the trade.

Full reference: use Copy for LLM above, or read /cli.md. See also the privacy policy.

Agent plugin artifacts