Yuzuup CLI (@yuzutask-project/cli)

Yuzuup is a task-management platform for software teams that works inside your IDE (Cursor, VS Code) and syncs with a Firebase-backed web dashboard. It is designed for agent-assisted development: roadmap tasks live in .yuzuup/tasks.json, Cursor agents use MCP tools to list, show, and update work, and optional Google AI helps with task breakdown and research.

Use Yuzuup when you want clear visibility in chat (create → implement → mark done → sync) without treating Firestore as the source of truth—your repo owns the roadmap, and backup pushes to the cloud for the team board.

What Yuzuup is for

• Roadmap tasks in the repo — Slug IDs, status, developer notes, epics, and sprints in .yuzuup/tasks.json, updated via tkl / npm run roadmap:* scripts.
• MCP in Cursor — project_list, task_list, task_show, task_update, epics, sprints, phases, research, and sync tools for AI agents (per-user project ACL).
• Web collaboration — Projects, delivery frameworks (Agile, PRINCE2, PMP), notifications, and a shared task board on Firebase Hosting.
• Optional AI — Gemini-backed breakdown and research when API keys are configured; local-first workflows when they are not.
• Multi-project — One global MCP install can serve many app repos; each project gets its own .yuzuup layout via tkl init.

Yuzuup is private software. See License below.

Install

Packages are on public npm (registry.npmjs.org). Maintainer guide: docs/developers/NPM_PUBLISH.md.

Requires Node.js 18+ and CLI 0.1.4+ for tkl auth login, MCP Cloud API session, and Yuzuup /connect/cursor sign-in.

Phase 1 — Install CLI from npm

npm install -g @yuzutask-project/cli@latest
tkl --version   # must show 0.1.4 or newer

Cold start (no global tkl yet):

npx -y @yuzutask-project/cli install-mcp

If install fails, remove any legacy @yuzutask-project:registry=… line from ~/.npmrc.

Phase 2 — Link MCP (Yuzuup sign-in)

tkl install-mcp    # installs/detects CLI, then opens /connect/cursor

Or re-link anytime:

tkl auth login

Restart Cursor after linking. MCP sign-in: Yuzuup — Google or email on /connect/cursor (tkl install-mcp / tkl auth login).

UI-first gate: setup also installs Cursor hooks so agents must create a Yuzu task and sync it to the live UI before editing files (npm run roadmap:task:create-and-sync or MCP task_create_in_db). Setup writes yuzu-agent-workflow.mdc so agents mark the task done after implementation (policy, not a hook). Docs: docs/developers/CURSOR_UI_FIRST_GATE.md.

External developers (no Firebase Admin): after tkl auth login, use project_list and sync_pull to sync shared projects via the MCP Cloud API. See docs/developers/MCP_CLOUD_API.md.

Phase 3 — Sync shared projects (MCP Cloud API)

tkl doctor --mcp    # verify identity + ~/.taskmanager/mcp-session.json
# In Cursor chat:
# @yuzuup-agent project_list
# @yuzuup-agent sync_pull projectId=YOUR_PROJECT_ID
tkl sync            # push/pull via cloud API (no service account on your machine)

Global CLI (manual — Yuzuup sign-in on /connect/cursor when email omitted):

tkl setup-cursor-global --launcher
tkl init    # run in each project directory

CI / scripts (no browser):

tkl setup-cursor-global --no-login [email protected] --user-uid=<firebase-auth-uid> --launcher

MCP only (no global install — complete Phase 1 .npmrc + auth first):

npx -y @yuzutask-project/cli setup-cursor-global --npx

Or add to ~/.cursor/mcp.json manually (prefer tkl auth login or setup commands to fill env automatically):

{
  "mcpServers": {
    "yuzuup-agent": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@yuzutask-project/cli"],
      "env": {
        "TASKMANAGER_USER_EMAIL": "[email protected]",
        "TASKMANAGER_USER_UID": "your-firebase-auth-uid"
      }
    }
  }
}

Or:

npx -y @yuzutask-project/cli setup-cursor-global --npx

Requires Node.js 18+.

Verify installation

tkl doctor --mcp
tkl --help

In a project after tkl init:

tkl status
tkl sync

Commands

| Command | Purpose | |---------|---------| | tkl install-mcp | Guided MCP + Cursor setup (AR/npm, /connect/cursor sign-in) and UI-first gate hooks | | tkl auth login | Yuzuup sign-in on /connect/cursor; saves identity + MCP cloud session (~/.taskmanager/mcp-session.json) | | tkl init | Bootstrap .yuzuup in the current project | | tkl sync | Push/pull tasks via Firebase Admin (maintainers) or MCP Cloud API (external devs) | | tkl status | Show sync and project status | | tkl setup-cursor-global | Global MCP in ~/.cursor/mcp.json + UI-first gate (skip with --no-ui-gate) | | tkl gate status\|arm\|bypass\|install | UI-first gate: require create-and-sync before agent file edits | | tkl doctor | Check Node, paths, MCP config, and UI-first gate |

Bins: tkl, tkl-mcp-launcher, yuzutask (MCP entry for npx).

Related packages

Published together under @yuzutask-project:

| Package | Role | |---------|------| | @yuzutask-project/cli | CLI and MCP launcher (this package) | | @yuzutask-project/mcp-server | MCP server (stdio) | | @yuzutask-project/gemini-service | Gemini API helpers | | @yuzutask-project/research-service | Custom Search + synthesis |

License

Proprietary — LicenseRef-YuzuTask-Proprietary. Authorized Inject Group / Yuzuup team members may install from company Artifact Registry or signed internal tarballs only. See LICENSE.

Publishing (maintainers)

See docs/developers/NPM_PUBLISH.md and docs/developers/ARTIFACT_REGISTRY_NPM.md in the Yuzuup monorepo.