English
Quick Start
CLI Quick Start

CLI Quick Start

Get the full workflow running from the command line in 5 minutes.

Install

npm install -g puppyone

Verify the installation:

puppyone --version

Sign in

puppyone auth login -e [email protected] -p password

After you sign in successfully, the CLI stores your credentials automatically, so you do not need to authenticate again for later commands.

Set your organization and project

puppyone org use "My Organization"
puppyone project use "My Project"

Once set, all later operations will target the current project by default.

Browse and create content

Content operations are performed via the REST API at /api/v1/content/{project_id}/.... Set up your variables first:

BASE_URL="https://api.puppyone.ai/api/v1/content/YOUR_PROJECT_ID"
TOKEN="YOUR_ACCESS_TOKEN"

List files

curl "$BASE_URL/ls" -H "Authorization: Bearer $TOKEN"

View the directory tree

curl "$BASE_URL/tree" -H "Authorization: Bearer $TOKEN"

Create directories

curl -X POST "$BASE_URL/mkdir" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "docs"}'
 
curl -X POST "$BASE_URL/mkdir" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "products"}'

Write content

# Write a Markdown file
curl -X POST "$BASE_URL/write" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "docs/readme.md",
    "content": "# Hello World",
    "node_type": "markdown",
    "message": "Add readme"
  }'
 
# Write a JSON file
curl -X POST "$BASE_URL/write" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "products/catalog.json",
    "content": [{"name": "Widget", "price": 99}],
    "node_type": "json",
    "message": "Add catalog"
  }'

You can also create and edit content through the Dashboard web UI.

Connect a data source

Sync data from external platforms into your content tree.

# Connect a Notion database to a target folder
puppyone access add notion https://notion.so/your-database-id --folder /docs

PuppyOne supports 15+ platforms including Notion, GitHub, Gmail, Google Drive, Linear, and Airtable.

Create an MCP endpoint

Create an entry point for MCP clients such as Cursor and Claude Desktop.

puppyone access add mcp "My API"

After creation, PuppyOne returns an MCP Server URL and API key that you can add to your client.

Sync a local folder

Sync a local folder to the cloud using the MUT protocol with version control.

# Already have a folder you want to sync? One shot:
puppyone access add filesystem docs --link ~/my-docs
 
# Or create the AP first, then choose: clone fresh or connect existing
puppyone access add filesystem docs
# Output shows two paths — pick whichever fits:
mut clone <url> --credential <key>                       # A) new folder
cd ~/my-docs && mut connect <url> --credential <key>     # B) existing folder
 
# Then edit, commit, push
cd ~/my-docs
echo "# Hello" > readme.md
mut commit -m "init"
mut push

Install the MUT CLI

The simple way:

pip install mutai

Ubuntu 24.04 / Debian 12+ — "pip not found" or "externally-managed-environment"

Recent Ubuntu/Debian releases ship without pip and forbid global installs through the system Python (PEP 668). Pick one of these:

# Recommended: install CLI tools with pipx into an isolated environment
sudo apt update && sudo apt install -y pipx
pipx ensurepath
pipx install mut
 
# Alternative: install pip and use a venv
sudo apt install -y python3-pip python3-venv
python3 -m venv ~/.venvs/mut
source ~/.venvs/mut/bin/activate
pip install mutai
 
# Not recommended: bypass PEP 668 (pollutes system Python)
pip install --break-system-packages mut

Verify with mut --version. If which mut returns nothing, add ~/.local/bin to PATH: export PATH="$HOME/.local/bin:$PATH".

Large files / slow networks: bump MUT_TIMEOUT

mut push uses a 60-second socket timeout by default. Large commits (multi-MB PDFs/videos) or a slow link will hit the wall and report "cannot reach server". Raise the limit:

# One-shot push (5 minutes)
MUT_TIMEOUT=300 mut push
 
# Or persist for the current shell
export MUT_TIMEOUT=300

Server-side limits: 200 MB per push, 50 MB per file. Exceeding either returns 413 with a hint on how to split the commit.

Check project status

# Project overview
puppyone status
 
# List all access points (sync, MCP, agent, local folder, and more)
puppyone access ls

Full example

Here is a complete flow from scratch:

# Install and sign in
npm install -g puppyone
puppyone auth login -e [email protected] -p password
 
# Select your project
puppyone org use "My Organization"
puppyone project use "My Project"
 
# Create content via REST API (or use the Dashboard)
BASE_URL="https://api.puppyone.ai/api/v1/content/YOUR_PROJECT_ID"
TOKEN="YOUR_ACCESS_TOKEN"
 
curl -X POST "$BASE_URL/mkdir" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "docs"}'
 
curl -X POST "$BASE_URL/write" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "docs/readme.md",
    "content": "# Product Knowledge Base",
    "node_type": "markdown",
    "message": "Initial readme"
  }'
 
# Connect Notion data
puppyone access add notion https://notion.so/db-id --folder /docs/notion
 
# Create an MCP endpoint for an agent
puppyone access add mcp "Production API"
 
# Sync a local folder (one-shot — links an existing folder)
puppyone access add filesystem workspace --link ~/workspace
# Or, if you don't have it locally yet, run `mut clone` from the printed output
 
# Check the results
puppyone access ls
puppyone status

Next steps

Self-HostedOverview