Local Folder Sync

puppyone access add filesystem creates a folder sync connection, then use the mut CLI for version-controlled sync — clone, commit, push, pull — a Git-like workflow.

Prerequisites

# Install PuppyOne CLI
npm install -g puppyone
 
# Install mut CLI (Python)
pip install mutai

Full Workflow

1. Log in and select a project

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

2. Create a filesystem sync connection

puppyone access add filesystem docs

docs is the cloud scope path — your local folder's contents sync to /docs in the project tree.

On success, the command prints both setup paths:

  Creating filesystem access point for scope "docs"... done

  ─ Pick one: clone fresh or connect existing

    A. New folder (no local files yet):
       mut clone http://api.puppyone.ai/api/v1/mut/ap/cli_xxx --credential cli_xxx

    B. Existing folder (use the files you already have):
       cd /path/to/your/folder
       mut connect http://api.puppyone.ai/api/v1/mut/ap/cli_xxx --credential cli_xxx

  ─ Or have us run option B for you next time:
    puppyone access add filesystem docs --link /path/to/your/folder

  ─ Then commit and push:
    mut commit -m "message" && mut push

  ─ Retrieve key later:
    puppyone access key <id>

3. Pick a setup path

Two options. Pick whichever matches your situation.

A. Clone to a fresh folder (no local files yet):

mut clone http://api.puppyone.ai/api/v1/mut/ap/cli_xxx --credential cli_xxx

This creates ./docs/ in the current directory and pulls any existing cloud content.

B. Connect an existing folder (you already have files locally):

cd /path/to/your/existing/folder
mut connect http://api.puppyone.ai/api/v1/mut/ap/cli_xxx --credential cli_xxx

mut connect pulls cloud state, three-way merges with whatever is on disk, then pushes the result. No overwrite, no data loss.

One-shot shortcut: skip steps 2 and 3 and let PuppyOne CLI run mut connect for you.
puppyone access add filesystem docs --link /path/to/your/folder

4. Edit locally, then commit and push

cd docs
 
# Edit files as usual
echo "# API Reference" > api.md
echo '{"version": "1.0"}' > config.json
 
# Commit and push to cloud
mut commit -m "add api docs"
mut push

5. Pull cloud changes

When others (or agents) make changes in the cloud:

cd docs
mut pull

Multi-folder sync to the same project

You can sync multiple local folders to different paths within the same project:

# One-shot — create the AP and link an existing folder in one step
puppyone access add filesystem docs --link ~/my-docs
puppyone access add filesystem code --link ~/my-code
 
# Or split it: create the AP, then clone (fresh) or connect (existing)
puppyone access add filesystem docs
mut clone   <docs-url> --credential <docs-key>           # fresh checkout
cd ~/existing-code && mut connect <code-url> --credential <code-key>

The cloud project tree becomes:

Root/
├── docs/          ← contents of ./docs/
│   ├── api.md
│   └── guide.md
└── code/          ← contents of ./code/
    ├── main.py
    └── utils.py

Managing connections

List all connections

puppyone access ls

View Access Key

Shown once on creation; retrieve anytime later:

puppyone access key <connection-id>

Regenerate Access Key

puppyone access key <connection-id> --regenerate

Delete a connection

puppyone access rm <connection-id>

MUT command reference

Command	Description
`mut clone <url> --credential <key>`	Clone the access point into a new local folder
`mut connect <url> --credential <key>`	Connect an existing local folder; three-way merges, no overwrite
`mut commit -m "message"`	Commit local changes
`mut push`	Push to cloud
`mut pull`	Pull cloud changes
`mut status`	View local change status
`mut log`	View commit history

Using with Claude Code / Cursor

Local folder sync is the best way to give AI coding tools access to PuppyOne data. Three flavours, pick the one that matches your situation:

# A) Local folder already exists → one-shot
puppyone access add filesystem workspace --link ~/ai-workspace
 
# B) Local folder doesn't exist yet → create AP, then clone
puppyone access add filesystem workspace
mut clone <url> --credential <key>
cd workspace
 
# C) Forgot --link, but the folder is already on disk → connect after the fact
puppyone access add filesystem workspace
cd ~/ai-workspace
mut connect <url> --credential <key>
 
# Open the directory in Claude Code or Cursor.
# After AI finishes editing, commit and push:
mut commit -m "AI updates"
mut push

All changes have version history and can be compared or rolled back at any time.

Troubleshooting

mut command not found

pip install mutai

Make sure mut is in your PATH.

Invalid Access Key

# Regenerate
puppyone access key <id> --regenerate

Push conflict

If the cloud has a newer version, pull first then push:

mut pull
mut commit -m "merge"
mut push

Unified Connection Management REST API Reference