Contribution Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• CLAUDE.md
• AGENTS.md
• README.md
• package.json
• SECURITY.md

This guide outlines the development workflow, architectural standards, and validation processes for contributors to the putio-cli repository. The project is a standalone TypeScript package built using the Effect ecosystem, designed to provide an agent-first interface for the put.io API.

The project prioritizes deterministic automation for machine agents while maintaining readable output for human users. Contributors are expected to maintain this balance by treating JSON output as the primary machine contract and terminal output as a separate adapter layer.
Sources: README.md:12-13, CLAUDE.md:6-23

Project Structure and Documentation

The repository follows a strict documentation hierarchy to ensure information remains accessible and relevant to specific audiences.

Location	Purpose
README.md	Top-level user-facing documentation and quick start.
CONTRIBUTING.md	Contributor-specific workflows and local setup instructions.
docs/	Deep implementation details and architectural boundaries.
skills/	Reusable consumer-facing agent guidance.
AGENTS.md / CLAUDE.md	Development instructions for AI agents working on the repo.
src/	Main source code, including commands and internal helpers.

Sources: CONTRIBUTING.md:43-48, CLAUDE.md:6-12, AGENTS.md:6-12

Local Development Setup

The project uses vite-plus (aliased as vp) for task orchestration and dependency management.

Initial Configuration

To set up the local environment, ensure you are using the Node.js version specified in package.json (Node 24.14+).

1. Install dependencies: vp install
2. Configure local VitePlus hook wiring: vp config
   Sources: CONTRIBUTING.md:7-14, package.json:49

Build and Run Cycles

Contributors can use the following commands for day-to-day development loops:

• Dev Mode: vp run dev starts the local build watcher.
• Manual Build: vp run build builds the CLI once.
• Testing Binaries: After building, the entrypoint can be tested via ./dist/bin.mjs describe.
  Sources: CONTRIBUTING.md:18-24, CLAUDE.md:27-33

Architecture and Coding Standards

The project relies heavily on the Effect library for managing side effects, services, and error handling.

Implementation Principles

• Effect-Native: Shared behavior should be moved into internal Effect-native helpers and services rather than bloating command modules.
• Typed Logic: Prefer using Effect services, layers, Schema, and tagged errors over ad-hoc control flow or standard JavaScript error handling.
• Contract Stability: JSON and NDJSON outputs are treated as stable machine contracts. Any changes to the public CLI surface must be reflected in README.md and skills/putio-cli/SKILL.md simultaneously.
  Sources: CLAUDE.md:37-45, AGENTS.md:37-45

Data Flow for CLI Commands

The following diagram illustrates the standard flow of a command execution from the CLI entrypoint through the internal service layers.

Validation and Testing

Validation is a critical step before opening or updating a pull request. The verify command serves as the primary repository gate.

Automated Checks

The project includes several layers of validation:

• Primary Gate: vp run verify (runs checks, smoke tests, and coverage).
• Static Analysis: vp run check for TypeScript linting and type checking.
• Unit Testing: vp run test.
• Code Coverage: vp run coverage.
• Specialized Builds: vp run build:sea and vp run verify:sea for Single Executable Application (SEA) validation.
  Sources: CONTRIBUTING.md:28-36, package.json:34-40

Testing Guidelines

• In-Process Tests: Prefer in-process tests unless the behavior specifically requires testing process boundaries.
• Command-Path Coverage: Add or update command-path tests specifically when the @effect/cli boundary changes.
• Behavior Changes: Always add or update tests when modifying existing behavior.
  Sources: CONTRIBUTING.md:55, CLAUDE.md:52-54, AGENTS.md:52-54

Security Policy

Security vulnerabilities should be reported privately to maintain project integrity.

Reporting Process

• Contact: Email devs@put.io for security or privacy issues.
• Guidelines: Testing must remain non-destructive and limited to accounts/data controlled by the contributor.
• Scope: Relevant issues include credential exposure, command injection, and authorization bypass.
  Sources: SECURITY.md:7-27

Pull Request Guidelines

To maintain a clean and maintainable codebase, contributors should follow these PR standards:

• Keep changes focused and explicit.
• Prefer small follow-up PRs over mixing unrelated cleanup or features into a single branch.
• Ensure that README.md and skills/ are updated if the command surface or setup flow changes.
  Sources: CONTRIBUTING.md:53-57, CLAUDE.md:44-46

The putio-cli project relies on the community to maintain its standard of "deterministic automation first." By following these guidelines, contributors ensure the CLI remains a reliable tool for both human users and automated agents.