Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
Installation and setup of the putio-cli involves deploying the binary across various platforms and configuring authentication to interact with the put.io API. The system is designed with an "agent-first" philosophy, supporting deterministic automation while remaining accessible for human users through readable terminal outputs.
The setup process encompasses environment validation (specifically Node.js versions for npm installs), binary retrieval through package managers or custom shell scripts, and the initialization of persistent configuration state for authentication and profile management.
Installation Methods
Homebrew
For macOS and Linux users utilizing Homebrew, the CLI is available via a dedicated tap.
brew tap putdotio/homebrew-tap
brew install putio-cli
Sources: README.md:32-35
macOS / Linux Shell Installer
A standalone shell script is provided for direct installation. This script detects the system architecture, downloads the appropriate prebuilt target, verifies its checksum, and installs the binary to a local directory.
The installer currently supports:
- macOS: Apple Silicon (arm64)
- Linux: x86_64 / amd64
The installer defaults to ~/.local/bin/putio but can be overridden using the INSTALL_DIR environment variable.
Sources: install.sh:17-41, install.sh:185-200, README.md:41-43
npm (Node.js)
The CLI is published as a TypeScript package and can be installed globally via npm. It requires Node.js version 24.14 or higher.
npm install --global @putdotio/cli
Sources: README.md:53-55, package.json:71-73
Configuration and State Persistence
The CLI maintains a persistent state for authentication tokens and profile settings. The location of the configuration file is resolved based on a specific hierarchy.
Config Path Resolution Logic
- Explicit Path: Defined by the
PUTIO_CLI_CONFIG_PATHenvironment variable. - XDG Home: If
XDG_CONFIG_HOMEis set, it uses$XDG_CONFIG_HOME/putio/config.json. - Default Home: Falls back to
~/.config/putio/config.json.
Sources: src/internal/state.test.ts:39-65
Persisted Schema
The configuration file is stored in JSON format with restricted file permissions (0o600).
| Field | Type | Description |
|---|---|---|
api_base_url | String | The base URL for the put.io API (default: https://api.put.io). |
auth_token | String | The OAuth2 token for the legacy or default profile. |
default_profile | String | The name of the profile to use if none is specified. |
profiles | Record | A collection of named profiles containing specific tokens and URLs. |
Sources: src/internal/state.test.ts:67-75, src/internal/state.test.ts:167-185
Authentication Setup
The CLI supports both interactive and headless authentication workflows.
Interactive Device Login
Users can authenticate by linking their account via a device code flow. This flow generates a code that must be entered at put.io/link.
Headless and Environment-Based Setup
For CI/CD or automation "agents," the CLI supports environment variable overrides that bypass persisted configuration.
PUTIO_CLI_TOKEN: Provides a direct API token. This takes precedence over all other auth methods.PUTIO_CLI_PROFILE: Selects a specific named profile from the configuration file.
Sources: README.md:144-146, src/internal/state.test.ts:285-300
Profile Management
Profiles allow managing multiple put.io accounts or environment-specific configurations (e.g., development vs. production).
# Create/Login to a named profile
putio auth login --profile automation-agent
# Switch default profile
putio auth profiles use automation-agent
# Remove a profile
putio auth profiles remove automation-agent
Sources: README.md:89-91, src/cli.test.ts:182-195
Environment Variables Summary
| Variable | Purpose |
|---|---|
PUTIO_CLI_TOKEN | Headless authentication; overrides all config files. |
PUTIO_CLI_PROFILE | Selects a persisted profile for the session. |
PUTIO_CLI_CONFIG_PATH | Overrides the default configuration file location. |
INSTALL_DIR | Customizes the binary destination for install.sh. |
PUTIO_CLI_VERSION | Pin a specific version during shell installation. |
Sources: README.md:144-150, install.sh:6-10
Development Setup
For contributors, the project requires specific tooling and a local build process.
- Dependencies: Managed via
pnpm(version11.0.0). - Tooling: Uses
vite-plus(vp) for lifecycle tasks. - Build Commands:
vp install: Install dependencies.vp run dev: Start build watcher.vp run build: Generate distribution assets in/dist.
Sources: CONTRIBUTING.md:7-18, package.json:75
Conclusion
Setting up putio-cli is a flexible process that accommodates different user environments through multiple installation vectors. Once the binary is present, the robust configuration system allows for seamless authentication transition between interactive human usage and automated agent sessions via environment variables or named profiles. Running putio version and putio auth status serves as the final verification that the installation and configuration are correctly established.