The official CLI for the Pinata API written in Go. Includes support for the Pinata Agents platform (beta).
Note
If you are on Windows please use WSL when installing. If you get an error that it was not able to resolve the github host run git config --global --unset http.proxy
The easiest way to install is to copy and paste this script into your terminal
curl -fsSL https://cli.pinata.cloud/install | bashIf you are on MacOS and have homebrew installed you can run the command below to install the CLI
brew install PinataCloud/ipfs-cli/ipfs-cli
To build and instal from source make sure you have Go installed on your computer and the following command returns a version:
go version
Then paste and run the following into your terminal:
git clone https://github.com/PinataCloud/ipfs-cli && cd ipfs-cli && go install .
As versions are released you can visit the Releases page and download the appropriate binary for your system, them move it into your bin folder.
For example, this is how I install the CLI for my Raspberry Pi
wget https://github.com/PinataCloud/ipfs-cli/releases/download/v0.1.0/ipfs-cli_Linux_arm64.tar.gz
tar -xzf ipfs-cli_Linux_arm64.tar.gz
sudo mv pinata /usr/bin
The Pinata CLI is equipped with the majority of features on both the Public IPFS API and Private IPFS API. It also includes support for AI Agents (beta).
With the CLI installed you will first need to authenticate it with your Pinata JWT. Run this command and follow the steps to setup the CLI!
pinata auth
Set a default IPFS network, can be either public or private. You can always change this at any time or override in individual commands. If none is set the default is public.
NAME:
pinata config - Configure Pinata CLI settings
USAGE:
pinata config command [command options] [arguments...]
COMMANDS:
network, net Set default network (public or private)
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
NAME:
pinata upload - Upload a file to Pinata
USAGE:
pinata upload [command options] [path to file]
OPTIONS:
--group value, -g value Upload a file to a specific group by passing in the groupId
--name value, -n value Add a name for the file you are uploading. By default it will use the filename on your system. (default: "nil")
--verbose Show upload progress (default: false)
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata files - Interact with your files on Pinata
USAGE:
pinata files command [command options] [arguments...]
COMMANDS:
delete, d Delete a file by ID
get, g Get file info by ID
update, u Update a file by ID
list, l List most recent files
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
NAME:
pinata files get - Get file info by ID
USAGE:
pinata files get [command options] [ID of file]
OPTIONS:
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata files list - List most recent files
USAGE:
pinata files list [command options] [arguments...]
OPTIONS:
--name value, -n value Filter by name of the target file
--cid value, -c value Filter results by CID
--group value, -g value Filter results by group ID
--mime value, -m value Filter results by file mime type
--amount value, -a value The number of files you would like to return
--token value, -t value Paginate through file results using the pageToken
--cidPending Filter results based on whether or not the CID is pending (default: false)
--keyvalues value, --kv value [ --keyvalues value, --kv value ] Filter results by metadata keyvalues (format: key=value)
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata files update - Update a file by ID
USAGE:
pinata files update [command options] [ID of file]
OPTIONS:
--name value, -n value Update the name of a file
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata files delete - Delete a file by ID
USAGE:
pinata files delete [command options] [ID of file]
OPTIONS:
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata groups - Interact with file groups
USAGE:
pinata groups command [command options] [arguments...]
COMMANDS:
create, c Create a new group
list, l List groups on your account
update, u Update a group
delete, d Delete a group by ID
get, g Get group info by ID
add, a Add a file to a group
remove, r Remove a file from a group
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
NAME:
pinata groups create - Create a new group
USAGE:
pinata groups create [command options] [name of group]
OPTIONS:
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata groups get - Get group info by ID
USAGE:
pinata groups get [command options] [ID of group]
OPTIONS:
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata groups list - List groups on your account
USAGE:
pinata groups list [command options] [arguments...]
OPTIONS:
--amount value, -a value The number of groups you would like to return (default: "10")
--name value, -n value Filter groups by name
--token value, -t value Paginate through results using the pageToken
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata groups add - Add a file to a group
USAGE:
pinata groups add [command options] [group id] [file id]
OPTIONS:
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata groups remove - Remove a file from a group
USAGE:
pinata groups remove [command options] [group id] [file id]
OPTIONS:
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata gateways - Interact with your gateways on Pinata
USAGE:
pinata gateways command [command options] [arguments...]
COMMANDS:
set, s Set your default gateway to be used by the CLI
open, o Open a file in the browser
link, l Get either an IPFS link for a public file or a temporary access link for a Private IPFS file
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
NAME:
pinata gateways set - Set your default gateway to be used by the CLI
USAGE:
pinata gateways set [command options] [domain of the gateway]
OPTIONS:
--help, -h show help
NAME:
pinata gateways link - Get either an IPFS link for a public file or a temporary access link for a Private IPFS file
USAGE:
pinata gateways link [command options] [cid of the file, seconds the url is valid for]
OPTIONS:
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata gateways open - Open a file in the browser
USAGE:
pinata gateways open [command options] [CID of the file]
OPTIONS:
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata keys - Create and manage generated API keys
USAGE:
pinata keys command [command options] [arguments...]
COMMANDS:
create, c Create an API key with admin or scoped permissions
list, l List and filter API key
revoke, r Revoke an API key
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
NAME:
pinata keys create - Create an API key with admin or scoped permissions
USAGE:
pinata keys create [command options] [arguments...]
OPTIONS:
--name value, -n value Name of the API key
--admin, -a Set the key as Admin (default: false)
--uses value, -u value Max uses a key can use (default: 0)
--endpoints value, -e value [ --endpoints value, -e value ] Optional array of endpoints the key is allowed to use
--help, -h show help
NAME:
pinata keys list - List and filter API key
USAGE:
pinata keys list [command options] [arguments...]
OPTIONS:
--name value, -n value Name of the API key
--revoked, -r Set the key as Admin (default: false)
--exhausted, -e Filter keys that are exhausted or not (default: false)
--uses, -u Filter keys that do or don't have limited uses (default: false)
--offset value, -o value Offset the number of results to paginate
--help, -h show help
NAME:
pinata keys revoke - Revoke an API key
USAGE:
pinata keys revoke [command options] [key]
OPTIONS:
--help, -h show help
NAME:
pinata swaps - Interact and manage hot swaps on Pinata
USAGE:
pinata swaps command [command options] [arguments...]
COMMANDS:
list, l List swaps for a given gateway domain or for your config gateway domain
add, a Add a swap for a CID
delete, d Remeove a swap for a CID
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
NAME:
pinata swaps list - List swaps for a given gateway domain or for your config gateway domain
USAGE:
pinata swaps list [command options] [cid] [optional gateway domain]
OPTIONS:
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata swaps add - Add a swap for a CID
USAGE:
pinata swaps add [command options] [cid] [swap cid]
OPTIONS:
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
NAME:
pinata swaps delete - Remeove a swap for a CID
USAGE:
pinata swaps delete [command options] [cid]
OPTIONS:
--network value, --net value Specify the network (public or private). Uses default if not specified
--help, -h show help
Warning
The Agents platform is currently in beta. Features and APIs may change.
Interact with AI agents on Pinata. Agents are hosted OpenClaw instances that can run tools, maintain context across conversations, and integrate with external services.
NAME:
pinata agents - Interact with AI agents on Pinata
USAGE:
pinata agents command [command options] [arguments...]
COMMANDS:
list, l List all agents
create, c Create a new agent
get, g Get agent details
delete, d Delete an agent
restart, r Restart an agent
logs Get agent logs
chat Interactive chat with an agent
exec Execute a command in an agent container
skills, sk Manage agent skills
secrets, sec Manage secrets
channels, ch Manage agent channels
devices, dev Manage agent devices
snapshots, snap Manage agent snapshots
tasks, t Manage agent cron jobs/tasks
ports, p Manage agent port forwarding
domains, dom Manage custom domains (beta)
files Agent file operations
templates, tpl Browse pre-built agent templates
clawhub, hub Browse and install skills from ClawHub
config, cfg Manage agent configuration
update, up Manage agent openclaw updates
versions, ver List available agent versions
feedback Submit feedback or feature request
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
NAME:
pinata agents list - List all agents
USAGE:
pinata agents list [command options] [arguments...]
OPTIONS:
--help, -h show help
NAME:
pinata agents create - Create a new agent
USAGE:
pinata agents create [command options] [arguments...]
OPTIONS:
--name value, -n value Name of the agent (required)
--description value, -d value Agent personality description
--vibe value Agent vibe/tagline
--emoji value Agent emoji
--skill value [ --skill value ] Skill CIDs to attach (can be specified multiple times)
--secret value [ --secret value ] Secret IDs to attach (can be specified multiple times)
--template value, -t value Template ID to deploy from (uses template snapshot, skills, and defaults)
--help, -h show help
Example with template:
# List available templates
pinata agents templates list
# Create agent from template
pinata agents create --name "My IPFS Agent" --template tpchchggStart an interactive chat session with an agent. Supports multiple output modes for different use cases.
NAME:
pinata agents chat - Interactive chat with an agent
USAGE:
pinata agents chat [command options] [agent ID] [optional prompt]
OPTIONS:
--model value Model override
--json Force JSONL output (auto-enabled when stdout is not a TTY)
--text Force plain text output (simpler alternative to JSONL for pipes)
--conversation, -C Multi-turn conversation mode (read messages from stdin line-by-line)
--session value Session key for conversation context
--help, -h show help
Output Modes:
| Mode | When | Use Case |
|---|---|---|
| Interactive TUI | TTY stdout | Human users in terminal |
| JSONL streaming | Non-TTY stdout (default) | Machine parsing, other agents |
Plain text (--text) |
Explicit flag | Simple scripts, easy piping |
Multi-turn (-C) |
Explicit flag | Conversations with context |
Examples:
# Interactive TUI mode
pinata agents chat <agent-id>
# Single message with plain text response
echo "Hello" | pinata agents chat --text <agent-id>
# Multi-turn conversation (each line is a message)
echo -e "Hello\nWhat is 2+2?" | pinata agents chat --text -C <agent-id>
# JSONL output for machine parsing
echo "Hello" | pinata agents chat <agent-id>
# Filter JSONL to extract just the text
echo "Hello" | pinata agents chat <agent-id> | jq -r 'select(.type=="content_delta") | .delta.text' | tr -d '\n'Execute a command inside an agent's container.
NAME:
pinata agents exec - Execute a command in an agent container
USAGE:
pinata agents exec [command options] [agent ID] [command]
OPTIONS:
--cwd value Working directory for the command
--help, -h show help
Examples:
# Run a simple command
pinata agents exec <agent-id> 'echo hello'
# List files in workspace
pinata agents exec <agent-id> 'ls -la /app'
# Run with specific working directory
pinata agents exec <agent-id> --cwd /app 'cat config.json'Read files from an agent's container.
NAME:
pinata agents files - Agent file operations
USAGE:
pinata agents files command [command options] [arguments...]
COMMANDS:
read, r Read a file from agent container
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
Examples:
# Read a file from the agent
pinata agents files read <agent-id> /app/config.jsonManage device pairing for agents (used for mobile/external device connections).
NAME:
pinata agents devices - Manage agent devices
USAGE:
pinata agents devices command [command options] [arguments...]
COMMANDS:
list, l List pending and paired devices
approve, a Approve a device pairing request
approve-all Approve all pending device requests
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
Examples:
# List devices for an agent
pinata agents devices list <agent-id>
# Approve a specific device request
pinata agents devices approve <agent-id> <request-id>
# Approve all pending requests
pinata agents devices approve-all <agent-id>NAME:
pinata agents skills - Manage agent skills
USAGE:
pinata agents skills command [command options] [arguments...]
COMMANDS:
list, l List available skills in library
create, c Create a new skill
delete, d Delete a skill from library
attach, a Attach skills to an agent
detach Detach a skill from an agent
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
NAME:
pinata agents secrets - Manage secrets
USAGE:
pinata agents secrets command [command options] [arguments...]
COMMANDS:
list, l List all secrets
create, c Create a new secret
update, u Update a secret value
delete, d Delete a secret
attach, a Attach secrets to an agent
detach Detach a secret from an agent
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
NAME:
pinata agents channels - Manage agent channels
USAGE:
pinata agents channels command [command options] [arguments...]
COMMANDS:
status, s Get channel configuration status
configure, c Configure a channel (telegram, slack, discord, whatsapp)
remove, r Remove a channel configuration
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
Examples:
# Get channel status
pinata agents channels status <agent-id>
# Configure Telegram
pinata agents channels configure <agent-id> telegram --bot-token <token>
# Remove a channel
pinata agents channels remove <agent-id> telegramNAME:
pinata agents snapshots - Manage agent snapshots
USAGE:
pinata agents snapshots command [command options] [arguments...]
COMMANDS:
list, l List agent snapshots
create, c Create a snapshot
status, s Get sync status
reset, r Reset to a snapshot
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
Examples:
# List snapshots
pinata agents snapshots list <agent-id>
# Check sync status
pinata agents snapshots status <agent-id>
# Create a snapshot
pinata agents snapshots create <agent-id>
# Reset to a snapshot
pinata agents snapshots reset <agent-id> <snapshot-cid>NAME:
pinata agents tasks - Manage agent cron jobs/tasks
USAGE:
pinata agents tasks command [command options] [arguments...]
COMMANDS:
list, l List tasks
create, c Create a new task
update, u Update an existing task
delete, d Delete a task
toggle Enable or disable a task
run Run a task immediately
history View task run history
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
Creating tasks:
# Create hourly task with system event
pinata agents tasks create --name "hourly-check" --every 1h --system-event "Check status" <agent-id>
# Create daily task with cron expression
pinata agents tasks create --name "daily-report" --cron "0 9 * * *" --agent-turn "Generate report" <agent-id>
# Create one-time task
pinata agents tasks create --name "scheduled-job" --at "2026-04-01T12:00:00Z" --system-event "Run once" <agent-id>Schedule types:
--every- Interval (e.g., "1h", "30m", "24h")--cron- Cron expression (e.g., "0 9 * * *")--at- One-time at ISO 8601 timestamp
Payload types:
--system-event- Triggers heartbeat-style execution--agent-turn- Triggers conversational response
Browse pre-built agent templates that provide ready-to-use configurations.
NAME:
pinata agents templates - Browse pre-built agent templates
USAGE:
pinata agents templates command [command options] [arguments...]
COMMANDS:
list, l List available templates
get, g Get template details
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
Examples:
# List all templates
pinata agents templates list
# List featured templates only
pinata agents templates list --featured
# Get template details
pinata agents templates get ipfs-expertBrowse and install skills from ClawHub, the community skills marketplace.
NAME:
pinata agents clawhub - Browse and install skills from ClawHub
USAGE:
pinata agents clawhub command [command options] [arguments...]
COMMANDS:
list, l List ClawHub skills
get, g Get skill details
install, i Install a ClawHub skill to your library
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
Examples:
# Browse available skills
pinata agents clawhub list
# Get skill details
pinata agents clawhub get clawdhub
# Install a skill to your library
pinata agents clawhub install <hub-skill-id>Manage custom domains for your agents (beta feature).
NAME:
pinata agents domains - Manage custom domains (beta)
USAGE:
pinata agents domains command [command options] [arguments...]
COMMANDS:
list, l List custom domains
add, a Register a custom domain
update, u Update a custom domain
delete, d Remove a custom domain
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
Examples:
# List domains for an agent
pinata agents domains list <agent-id>
# Add a subdomain (myapp.apps.pinata.cloud)
pinata agents domains add <agent-id> --subdomain myapp --port 8080
# Add a custom domain
pinata agents domains add <agent-id> --domain api.example.com --port 3000 --protected
# Update domain
pinata agents domains update <agent-id> <domain-id> --port 8081
# Remove domain
pinata agents domains delete <agent-id> <domain-id>Manage agent port forwarding rules.
NAME:
pinata agents ports - Manage agent port forwarding
USAGE:
pinata agents ports command [command options] [arguments...]
COMMANDS:
list, l List port forwarding rules
set, s Set port forwarding rules
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
Examples:
# List current port mappings
pinata agents ports list <agent-id>
# Set port forwarding (port:pathPrefix format)
pinata agents ports set <agent-id> 8080:/api 3000:/appManage agent openclaw configuration.
NAME:
pinata agents config - Manage agent configuration
USAGE:
pinata agents config command [command options] [arguments...]
COMMANDS:
get, g Read openclaw config
set, s Write openclaw config
validate, v Validate openclaw config
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
Examples:
# Read current config
pinata agents config get <agent-id>
# Validate config
pinata agents config validate <agent-id>
# Set config (JSON string)
pinata agents config set <agent-id> '{"key": "value"}'Manage openclaw version updates.
NAME:
pinata agents update - Manage agent openclaw updates
USAGE:
pinata agents update command [command options] [arguments...]
COMMANDS:
check, c Check for openclaw updates
apply, a Apply openclaw update
help, h Shows a list of commands or help for one command
OPTIONS:
--help, -h show help
Examples:
# Check for updates
pinata agents update check <agent-id>
# Apply latest update
pinata agents update apply <agent-id>
# Apply specific version
pinata agents update apply <agent-id> --tag 2026.3.8List available agent image versions.
NAME:
pinata agents versions - List available agent versions
USAGE:
pinata agents versions [agent ID]
OPTIONS:
--help, -h show help
Example:
pinata agents versions <agent-id>If you have any questions please feel free to reach out to us!