@giveusaproject/addon-cli

gyap is the command-line tool for building add-ons for Give Us a Project: create one from a template, check it with the same checks the app runs, test it on practice data, preview its views, and upload a new version. It works the same for a person at a terminal, a CI job and an AI coding tool (every command takes --json, and gyap mcp is an MCP server).

npx @giveusaproject/addon-cli create weekly-summary --template schedule
cd weekly-summary && npm install
npx gyap check .      # the same checks the app runs before it turns an add-on on
npm test              # the add-on's own tests, on practice data
npx gyap preview .    # its views with practice data
GIVEUSAPROJECT_API_KEY=… npx gyap upload . --workspace your-workspace

Or install it once: npm install -g @giveusaproject/addon-cli. Needs Node 22 or later.

Commands

| Command | What it does | |---|---| | gyap create <folder> [--template card\|schedule\|tool] [--name "…"] | a new add-on folder (with its own AGENTS.md) | | gyap templates | the templates | | gyap check [folder] | builds it as the app does and runs the app's checks | | gyap test [folder] | its own tests; handlers run in the same isolate the app uses | | gyap preview [folder] | its views with practice data; run schedules and tools by hand | | gyap pack [folder] | the package file it would upload (.ttb) | | gyap upload [folder\|file.ttb] [--workspace slug] | sends a new version; the app checks it again | | gyap guide | the full guide | | gyap mcp | an MCP server over stdio with the same actions as tools |

--json prints one object on stdout: { "ok": true, "command": "check", "data": { … } }, or { "ok": false, …, "error": { "code": "CHECKS_FAILED", "message": "…", "hint": "…" } }.

Exit codes: 0 done, 1 the add-on has problems, 2 wrong usage, 3 the app couldn't be reached or refused the key, 4 the tool itself failed.

AI coding tools

• Claude Code: claude mcp add giveusaproject -- npx -y @giveusaproject/addon-cli mcp
• Cursor, Windsurf, VS Code (Copilot) and other MCP clients: command npx, args ["-y", "@giveusaproject/addon-cli", "mcp"].
• Agent Skills: skills/giveusaproject-addons/SKILL.md in this package; also AGENTS.md and llms.txt.
• Anything else: run the commands with --json.

MCP tools: addon_guide, addon_templates, addon_create, addon_check, addon_test, addon_pack, addon_upload.

Privacy and safety

• No tracking or telemetry. Nothing is sent anywhere except the upload you ask for, to the app's documented upload endpoint (POST /api/bundles/upload).
• Uploads use an API key you make in the app (account settings, API keys) with the add-on permission. Keys expire and can be revoked there. The tool reads it from GIVEUSAPROJECT_API_KEY; it never stores it and the MCP server never takes it as an argument.
• The app runs the same checks again on every upload, and people see what an add-on can do before they turn it on. An admin agrees to anything new a later version asks for.

Licence

MIT