CLI Installation & Configuration

PuppyOne CLI (puppyone) is a command-line tool that gives you direct access to the PuppyOne platform from your terminal: project management, access point configuration, agent chat, and more.

Install

Install it globally with npm:

npm install -g puppyone

After installation, verify the version:

puppyone -V

First-time setup

After installing, complete three setup steps: log in, choose an organization, and choose a project.

# 1. Log in
puppyone auth login -e [email protected] -p password
 
# 2. Select an organization
puppyone org use "My Organization"
 
# 3. Select a project
puppyone project use "My Project"

Once finished, the CLI stores the current state in its config file, and later commands automatically use the selected organization and project.

Global options

All commands support these global options:

Option	Description
`-V, --version`	Show the version number
`-u, --api-url <url>`	Specify the API URL and override the config file
`-k, --api-key <key>`	Specify an API key or token and override the config file
`--json`	Output JSON, useful for scripts and AI agents
`-v, --verbose`	Show verbose output
`-p, --project <id>`	Specify a project ID and override the active project
`-o, --org <id>`	Specify an organization ID and override the active organization

Example: temporarily run a command against a different project without changing global config:

puppyone access ls -p proj_abc123

JSON output

Every command supports --json, which returns machine-readable JSON for integration with scripts, tooling, and AI agents:

puppyone access ls --json

Config file

CLI configuration is stored in ~/.puppyone/config.json, including the API URL, login credentials, and the active organization and project.

Config commands

# Show current config
puppyone config show
 
# Set a config value
puppyone config set api_url https://api.puppyone.ai
 
# Show config file path
puppyone config path
 
# Reset config
puppyone config reset

Command groups

PuppyOne CLI is organized into these command groups:

Command	Description
`puppyone auth`	Log in, log out, and inspect the current user
`puppyone org`	Organization management
`puppyone project`	Project management
`puppyone access`	Unified access point management (data sources, agents, MCP, sandboxes, filesystem sync)
`puppyone data`	Remote file system operations (browse, read, write, move, delete)
`puppyone chat`	Agent chat
`puppyone config`	CLI configuration management
`puppyone status`	Project dashboard

puppyone data provides familiar commands like ls, cat, write, mv, and rm to operate directly on the cloud content tree. Version management (history, diff, rollback) is available via the REST API.

Common workflows

Add a data source and sync it

puppyone access add notion https://notion.so/page-id --folder /notion-data
puppyone access ls

Create an agent and chat

puppyone access add agent "My Bot" --model gpt-4o
puppyone chat

Create an MCP endpoint

puppyone access add mcp "My Data"

Mount a local folder

puppyone access add filesystem ~/workspace

Operate on cloud files

# Browse a directory
puppyone data ls /docs
 
# Read a file
puppyone data cat /docs/readme.md
 
# Write a file
puppyone data write /config.json --content '{"theme": "dark"}'

Check project status

puppyone status
puppyone access ls

Get help

Append --help to any command to see usage details:

puppyone --help
puppyone access --help
puppyone auth --help

Code Sandbox Remote File Operations