Fold CLI

Manage todos in a self-hosted Fold installation from a terminal or AI agent.

npm install --global @jackcuthbert/fold-cli
fold-cli auth login
fold-cli skill install --agent codex --scope user
fold-cli todo list
fold-cli todo create "Book dentist" --list Personal
fold-cli todo create "Book dentist" --list Personal --due 2026-10-05
fold-cli todo create "Book dentist" --list Personal --notes "Call after 3pm" --priority high
fold-cli todo edit TODO_UID --due 2026-10-05T09:30
fold-cli todo edit TODO_UID --notes "Ask for Dr. Lee" --priority medium
fold-cli todo edit TODO_UID --clear-due --clear-notes --clear-priority
fold-cli todo edit TODO_UID --list Work
fold-cli todo uncomplete TODO_UID --yes

Run fold-cli --help for the complete command list. Add --json to any data command for machine-readable output.

Due dates accept YYYY-MM-DD all-day values or local YYYY-MM-DDTHH:mm[:ss] datetimes. Local times use the machine's IANA timezone; offsets and Z are rejected. Create accepts --notes TEXT and --priority high|medium|low, which may be combined with each other and --due. Edit accepts --notes TEXT, --priority high|medium|low, --clear-notes, and --clear-priority; edits may combine these with summary and due changes. Set and clear flags for the same field cannot be combined. Notes are preserved verbatim, including empty text; use --clear-notes to remove them. A 412 conflict retries once only when every edited field is unchanged on the fresh todo.

Edit with --list TARGET moves the todo to another list: the source is resolved by UID, TARGET is the destination resolved like create, and the CLI copies the todo into TARGET before deleting the source, so the copy keeps its fields. A completed todo and a TARGET equal to the todo's own list are rejected. Uncomplete reopens a completed todo and requires confirmation; --yes/-y skips the prompt and --json requires it. An already-open todo is reported as success unchanged.

Install the bundled fold-todos agent skill with --agent codex, --agent claude, or --agent all and --scope user or --scope project. Omitting --agent installs to the shared agent skills directory. Existing skill files are not overwritten.

The CLI stores Fold's encrypted session cookie, not the plaintext CalDAV password. Regular use renews the session; after seven inactive days, run fold-cli auth login again.

Migrating from the fold command

The executable is now fold-cli to avoid conflicting with the system's fold text-wrapping command. After the release is published, replace the old installation so its fold executable is removed:

npm uninstall --global @jackcuthbert/fold-cli
npm install --global @jackcuthbert/fold-cli@latest
fold-cli auth status

Use the package manager and installation scope used for your original install. Replace fold with fold-cli in scripts, shell aliases, and agent instructions; remove aliases or symlinks that make fold invoke the Fold CLI. Subcommands, flags, environment variables, and saved session locations are unchanged, so an unexpired session still works without signing in again.

Previously installed agent skills still invoke fold. Update their commands or move the existing SKILL.md outside its skill directory as a backup, then reinstall with fold-cli skill install using the same --agent and --scope. The installer refuses to overwrite an existing file. Skill directories are .codex/skills/fold-todos, .claude/skills/fold-todos, or .agents/skills/fold-todos, under your home directory for user scope or the project for project scope. Repeat for every installed agent and scope, and restart the agent session to load the updated instructions.