Contributing

Thanks for contributing to putio-cli.

Setup

Use the Node version required by package.json, then install dependencies:

pnpm exec vp install

Then install the stock VitePlus hook wiring for this clone:

pnpm exec vp config

Start the local build watcher:

pnpm exec vp run dev

Build the CLI once and try the shipped entrypoint:

pnpm exec vp run build
./dist/bin.mjs describe

Run the main repository gate before opening or updating a pull request:

pnpm exec vp run verify

Use the repo-local Vite+ binary for test-bearing commands so the runner and vite-plus/test imports share one Vitest runtime.

Run focused checks when they match your change:

pnpm exec vp run check:dead-code
pnpm exec vp run smoke:pack
pnpm exec vp run build:sea
pnpm exec vp run verify:sea

See Distribution for release automation, credentials, and binary asset publishing.

verify is the repository delivery gate.
verify enforces the production Effect runtime boundary and dead-code checks, exercises the packed CLI through success and failure paths, and writes the smoke report to .artifacts/smoke-packed-install.json.
pnpm exec vp config installs the tracked pre-commit and pre-push hooks; pre-push runs the same verify gate as CI.
Prefer pnpm exec vp install, pnpm exec vp test, and pnpm exec vp check for day-to-day local loops.
Keep the exact Effect versions, the Effect override, and the pnpm SDK compatibility patch aligned. The build bundles the patched SDK so installed CLIs and the SDK share one Effect runtime.
Keep top-level user docs in README.md and contributor workflow here.
Put deeper implementation detail in docs/ instead of growing the top-level docs.
Keep AGENTS.md as repo-development guidance and skills/* as consumer-facing agent guidance.
When the public CLI surface or agent setup flow changes, update README.md and skills/putio-cli/* in the same change.

Keep changes focused and explicit.
Add or update tests when behavior changes.
Prefer small follow-up pull requests over mixing unrelated cleanup into one branch.