English
CLI Reference
Remote File Operations

Remote File System Operations

puppyone data lets you operate on your PuppyOne cloud workspace directly from the terminal — browse, read, write, move, and delete files and folders without opening a browser.

This is the same content tree you see in the web UI, now accessible from any terminal, script, or AI agent.

Command Reference

CommandDescription
data ls [path]List directory contents
data cat <path>Read file contents
data tree [path]Show directory tree
data stat <path>Show file/directory info
data write <path>Write a file
data touch <path>Create an empty file
data mkdir <path>Create a directory
data cp <src> <dst>Copy a file
data mv <src> <dst>Move or rename
data rm <path>Delete (moves to trash by default)
data trashList trash contents
data restore <path>Restore from trash

All commands support --json output.

Browse & Read

List a directory

# List the root
puppyone data ls
 
# List a specific directory
puppyone data ls /docs
 
# Detailed mode (type, size, hash)
puppyone data ls /docs -l

Read a file

puppyone data cat /docs/readme.md
 
# JSON files are auto-formatted
puppyone data cat /config/settings.json

Directory tree

# Full tree from root
puppyone data tree
 
# Specify starting path and depth
puppyone data tree /docs --depth 2

File info

puppyone data stat /docs/readme.md

Returns path, type, size, MIME type, content hash, and more.

Create & Write

Write a file

The write command accepts content from three sources: inline text, a local file, or stdin.

# Inline JSON
puppyone data write /config.json --content '{"theme": "dark"}'
 
# From a local file
puppyone data write /docs/guide.md --file ~/local-guide.md
 
# From a pipe
echo "Hello World" | puppyone data write /docs/hello.md
 
# With a commit message
puppyone data write /config.json --content '{}' -m "reset config"

File type is auto-detected from the extension (.json → json, .md → markdown). Override with --type.

Create an empty file

puppyone data touch /docs/draft.md
puppyone data touch /data/empty.json

Create a directory

puppyone data mkdir /docs/guides

File Management

Copy

puppyone data cp /docs/readme.md /backup/readme.md

Move or rename

puppyone data mv /docs/old-name.md /docs/new-name.md

Delete

# Moves to trash (recoverable)
puppyone data rm /docs/outdated.md
 
# Permanent delete
puppyone data rm /docs/outdated.md --force

Trash

# View trash contents
puppyone data trash
 
# Restore a file
puppyone data restore .trash/docs/outdated.md

Scripting & AI Agent Integration

All commands support --json for automation:

# List all file names
puppyone data ls /docs --json | jq '.entries[].name'
 
# Read a JSON file and extract a field
puppyone data cat /config.json --json | jq '.content.theme'
 
# Pipe external API data into PuppyOne
curl -s https://api.example.com/data | puppyone data write /imports/api-data.json

In CI/CD pipelines

# Authenticate with an API key (no interactive login)
puppyone data ls / --api-key $PUPPYONE_KEY --project $PROJECT_ID --json

Relationship to the REST API

puppyone data commands are a CLI wrapper around the PuppyOne content REST API. Both operate on the same content tree; choose based on your use case:

  • CLI: Terminal workflows, scripts, AI coding tool integration
  • REST API: Application code, custom integrations, bulk operations (bulk-write), version management (versions, diff, rollback)

Version management (history, diff, rollback) is currently only available via the REST API. See the File System Commands docs.

Install & ConfigureFile System REST API