Kaname CLI

Command-line client for Kaname. See docs/cli-plan.md for the design.

The package ships two binaries: kaname (the CLI) and kaname-mcp (an MCP server exposing the same operations as tools — see MCP server).

Install

npm install -g @kaname-tasks/kaname   # installs the `kaname` and `kaname-mcp` binaries
# or run without installing:
npx @kaname-tasks/kaname ls

Requires Node.js >= 20. The CLI talks to the hosted backend (https://kaname-api-p0su.onrender.com) by default — no configuration needed. Point it elsewhere with KANAME_API_URL or kaname login --api-url ....

Install from the monorepo (for development)

cd cli
npm install
npm run build
npm link        # makes `kaname` and `kaname-mcp` available on your PATH

For local development against a backend on your machine, override the default:

export KANAME_API_URL=http://localhost:8000

Login

kaname login                 # Google sign-in via your browser (default)
kaname login --password      # email/password prompt
kaname login --api-url https://api.example.com   # persist a backend URL

Google login needs a "Desktop app" OAuth client from the same Google Cloud project as the web app, provided via KANAME_GOOGLE_CLIENT_ID / KANAME_GOOGLE_CLIENT_SECRET (or googleClientId / googleClientSecret in ~/.config/kaname/config.json). The backend must list that client id in GOOGLE_CLI_CLIENT_ID.

Tokens are stored in ~/.config/kaname/credentials.json (mode 0600) and refresh automatically; you only re-login after 30+ days of inactivity.

Usage

kaname add buy milk --list groceries --when today
kaname add call mom --when fri --due +7d --notes "she prefers evenings"

kaname ls                # today view (default)
kaname ls --inbox        # todos with no list
kaname ls --all
kaname ls --list groceries
kaname ls --smart errands

kaname show 4f2a1c        # short ids are shown by `kaname ls` and never change
kaname done 4f2a1c 9bd003  # complete several at once
kaname undone 9bd003
kaname edit 4f2a1c --when tomorrow --list none
kaname rm 4f2a1c           # asks for confirmation (or --force)

kaname subtask add 4f2a1c whole milk
kaname subtask done 4f2a1c 1
kaname subtask rm 4f2a1c 2

kaname list ls
kaname list add groceries --color '#22c55e'
kaname list rename groceries errands
kaname list rm errands

kaname whoami
kaname logout

Dates accept today, tomorrow, weekday names (fri), offsets (+3d), ISO (2026-07-10), and none to clear a date in edit.

Any command taking a todo accepts three ways to name one:

| Form | Example | Notes | |---|---|---| | short id | 4f2a1c | Shown by ls; the leading chars of the todo's uuid, so it never changes | | #-index | #2 or 2 | Position in the last ls output — convenient, but shifts whenever you re-list | | full uuid | 4f2a1c… | What --json and --plain print |

Prefer the short id: an index means whatever the most recent ls in any shell put in that row, so it goes stale the moment you list something else.

Every read command takes --json (raw API response, for jq/scripts) and --plain (tab-separated, no color). Exit codes: 1 for errors, 2 for "not logged in / session expired".

Development

npm run dev -- ls        # run from source
npm run lint             # typecheck
npm test                 # unit tests
npm run generate-types   # regenerate src/api/types.ts from a running backend

src/api/types.ts is generated from the backend OpenAPI spec and committed. Regenerate it after changing any Pydantic schema (same rule as the frontend).

MCP server

kaname-mcp is a Model Context Protocol server that lets an AI assistant (Claude Desktop, Claude Code, …) read and manage your kaname todos. It's a stdio server that reuses the CLI's stored session — so log in once with kaname login, and the MCP server picks up the same credentials (with automatic token refresh). No separate auth.

Tools

Full parity with the CLI:

• Todos: list_todos, get_todo, add_todo, update_todo, complete_todo, reopen_todo, delete_todo
• Subtasks: add_subtask, update_subtask, delete_subtask
• Lists: list_lists, list_smart_lists, create_list, rename_list, delete_list

Todos and subtasks are addressed by id (uuid); list_todos returns those ids. Lists accept either a name or an id.

Connect it

Claude Code:

claude mcp add kaname -- kaname-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "kaname": { "command": "kaname-mcp" }
  }
}

If kaname-mcp isn't on the client's PATH (GUI apps often have a minimal one), use an absolute path — which kaname-mcp to find it — or point at the built file: "command": "node", "args": ["/abs/path/to/cli/dist/mcp.js"].

To target a non-default backend, set KANAME_API_URL (or persist it via kaname login --api-url … before connecting).