Use this file to discover all available pages before exploring further.
The Agents feature is currently in beta.
The pinata agents commands let you manage your Pinata Agents directly from the terminal. Create agents, start chat sessions, manage skills and secrets, configure channels, and more.
New to Agents?
Learn about the Pinata Agents platform and get started with hosted AI agents.
NAME: pinata agents - Interact with AI agents on PinataUSAGE: pinata agents [command [command options]]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, c 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 and manage 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 engines List the agent engines enabled for this deployment auth Authenticate with a provider and store the credential as a secret feedback Submit feedback or feature requestOPTIONS: --help, -h show help
NAME: pinata agents create - Create a new agentUSAGE: pinata agents create [options]OPTIONS: --name string, -n string Name of the agent (required) --description string, -d string Agent personality description --vibe string Agent vibe/tagline --emoji string Agent emoji --engine string Container engine: openclaw (default) or hermes --skill string [ --skill string ] Skill CIDs to attach (can be specified multiple times) --secret string [ --secret string ] Secret IDs to attach (can be specified multiple times) --template string, -t string Template ID to deploy from (uses template snapshot, skills, and defaults) --user-name string Owner display name (written into workspace/USER.md) --user-email string Owner email (written into workspace/USER.md) --channels string Channel config as JSON (for Hermes agents; set at creation to avoid a restart), e.g. '{"telegram":{"botToken":"...","dmPolicy":"open"}}' --help, -h show help
--engine selects the container engine. It defaults to openclaw server-side; pass hermes for the opinionated engine. Run pinata agents engines to see which engines your deployment allows. See Concepts → Engine for the differences.Example with template:
# List available templatespinata agents templates list# Create agent from templatepinata agents create --name "My IPFS Agent" --template tpchchgg
Example with a Hermes engine and channels:Pass --channels as a JSON object to configure Telegram, Slack, or Discord at creation for engines that support create-time channel bootstrap. This is especially useful for Hermes agents because the channel can come up with the agent and avoid a post-create restart. The per-channel fields (botToken, appToken, dmPolicy, allowFrom) match the Channels API and the channels block in manifest.json.
# Create a Hermes agentpinata agents create --name "My Hermes Agent" --engine hermes# Create a Hermes agent with Telegram configured at creationpinata agents create \ --name "My Hermes Agent" \ --engine hermes \ --user-name "Ada Lovelace" \ --user-email "ada@example.com" \ --channels '{"telegram":{"botToken":"123:abc","dmPolicy":"open"}}'
NAME: pinata agents exec - Execute a command in an agent containerUSAGE: pinata agents exec [options] [agent ID] [command]OPTIONS: --cwd string Working directory for the command --help, -h show help
Examples:
# Run a simple commandpinata agents exec <agent-id> 'echo hello'# List files in workspacepinata agents exec <agent-id> 'ls -la /app'# Run with specific working directorypinata agents exec <agent-id> --cwd /app 'cat config.json'
Manage device pairing for agents (used for mobile/external device connections).
NAME: pinata agents devices - Manage agent devicesUSAGE: pinata agents devices [command [command options]]COMMANDS: list, l List pending and paired devices approve, a Approve a device pairing request approve-all Approve all pending device requestsOPTIONS: --help, -h show help
Examples:
# List devices for an agentpinata agents devices list <agent-id># Approve a specific device requestpinata agents devices approve <agent-id> <request-id># Approve all pending requestspinata agents devices approve-all <agent-id>
NAME: pinata agents skills - Manage agent skillsUSAGE: pinata agents skills [command [command options]]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 agentOPTIONS: --help, -h show help
create options:
OPTIONS: --cid string Content ID of the skill (required) --name string, -n string Skill name (required) --description string, -d string Skill description --env string [ --env string ] Required environment variable names --file-id string Pinata v3 file ID --help, -h show help
Examples:
# List skills in your librarypinata agents skills list# Create a skill from a CIDpinata agents skills create --cid <skill-cid> --name "My Skill" --env API_KEY# Attach skills to an agentpinata agents skills attach <agent-id> <skill-cid> <skill-cid># Detach a skill from an agentpinata agents skills detach <agent-id> <skill-id>
NAME: pinata agents secrets - Manage secretsUSAGE: pinata agents secrets [command [command options]]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 agentOPTIONS: --help, -h show help
create options:
OPTIONS: --name string, -n string Secret name (e.g. ANTHROPIC_API_KEY) --value string, -v string Secret value --help, -h show help
Examples:
# Create a secretpinata agents secrets create --name ANTHROPIC_API_KEY --value sk-ant-...# Update a secret's valuepinata agents secrets update <secret-id> --value sk-ant-...# Attach secrets to an agentpinata agents secrets attach <agent-id> <secret-id> <secret-id>
NAME: pinata agents channels - Manage agent channelsUSAGE: pinata agents channels [command [command options]]COMMANDS: status, s Get channel configuration status configure, c Configure a channel (telegram, slack, discord, whatsapp) remove, r Remove a channel configurationOPTIONS: --help, -h show help
configure options:
OPTIONS: --bot-token string Bot token --app-token string App token (Slack only) --dm-policy string DM policy: open or pairing --allow-from string [ --allow-from string ] Allowed user IDs/phone numbers --enabled Enable or disable the channel --skip-restart Skip restarting the agent after configuring --help, -h show help
Pass --skip-restart to batch multiple channel changes and avoid a gateway restart per call; the new configuration takes effect on the next restart.Examples:
# Get channel statuspinata agents channels status <agent-id># Configure Telegrampinata agents channels configure <agent-id> telegram --bot-token <token># Configure a channel without restarting the agentpinata agents channels configure <agent-id> telegram --bot-token <token> --skip-restart# Disable a channel without removing its configurationpinata agents channels configure <agent-id> telegram --enabled=false# Remove a channelpinata agents channels remove <agent-id> telegram
NAME: pinata agents snapshots - Manage agent snapshotsUSAGE: pinata agents snapshots [command [command options]]COMMANDS: list, l List agent snapshots create, c Create a snapshot status, s Get sync status reset, r Reset to a snapshotOPTIONS: --help, -h show help
Examples:
# List snapshotspinata agents snapshots list <agent-id># Check sync statuspinata agents snapshots status <agent-id># Create a snapshotpinata agents snapshots create <agent-id># Reset to a snapshotpinata agents snapshots reset <agent-id> <snapshot-cid>
NAME: pinata agents tasks - Manage agent cron jobs/tasksUSAGE: pinata agents tasks [command [command options]]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 historyOPTIONS: --help, -h show help
NAME: pinata agents tasks create - Create a new taskUSAGE: pinata agents tasks create [options] [agent ID]DESCRIPTION: Create a new cron job for an agent. Schedule types: --at Run once at a specific time (ISO 8601 format) --every Run at intervals (e.g., "1h", "30m", "24h") --cron Run on a cron schedule (e.g., "0 9 * * *") Payload types (choose one): --system-event System event text (triggers heartbeat-style execution) --agent-turn Agent turn message (triggers conversational response) Examples: # Run every hour with a system event pinata agents tasks create <agent-id> --name "hourly-check" --every 1h --system-event "Check for updates" # Run daily at 9am UTC with agent turn pinata agents tasks create <agent-id> --name "daily-report" --cron "0 9 * * *" --agent-turn "Generate daily report" # Run once at a specific time pinata agents tasks create <agent-id> --name "one-time" --at "2026-04-01T12:00:00Z" --system-event "Do task"OPTIONS: --name string, -n string Task name (required) --description string Task description --disabled Create task in disabled state --at string Run once at this time (ISO 8601) --every string Run every interval (e.g., 1h, 30m) --cron string Cron expression (e.g., '0 9 * * *') --tz string Timezone for cron schedule --system-event string System event payload text --agent-turn string Agent turn message --model string Model override for agent turn --timeout int Timeout in seconds (default: 0) --session string Session target: main or isolated (default: "main") --skill string [ --skill string ] Skill CIDs to make available to the task (can be specified multiple times) --help, -h show help
NAME: pinata agents tasks update - Update an existing taskUSAGE: pinata agents tasks update [options] [agent ID] [job ID]DESCRIPTION: Update an existing cron job. Only specified fields are changed. Examples: # Change task name pinata agents tasks update <agent-id> <job-id> --name "new-name" # Update schedule to run every 2 hours pinata agents tasks update <agent-id> <job-id> --every 2h # Update payload message pinata agents tasks update <agent-id> <job-id> --system-event "New message"OPTIONS: --name string, -n string New task name --description string New task description --at string Run once at this time (ISO 8601) --every string Run every interval (e.g., 1h, 30m) --cron string Cron expression (e.g., '0 9 * * *') --tz string Timezone for cron schedule --system-event string System event payload text --agent-turn string Agent turn message --model string Model override for agent turn --timeout int Timeout in seconds (default: 0) --skill string [ --skill string ] Skill CIDs to make available to the task (can be specified multiple times) --help, -h show help
Scoping skills to a task:create and update accept --skill (repeatable) to make specific skill CIDs available only while the task runs:
# Create a task with task-scoped skillspinata agents tasks create --name "nightly-report" --cron "0 0 * * *" \ --agent-turn "Summarize today" --skill <skill-cid> --skill <skill-cid> <agent-id># Add or change task-scoped skills on an existing taskpinata agents tasks update <agent-id> <task-id> --skill <skill-cid>
Browse and manage agent templates. Includes browsing published templates and submitting your own from a GitHub/GitLab repository.
NAME: pinata agents templates - Browse and manage agent templatesUSAGE: pinata agents templates [command [command options]]COMMANDS: list, l List available templates get, g Get template details by slug mine List templates you have submitted validate, v Validate a git repo for template submission submit, s Submit a new template from a git repo update, u Update an existing template submission (re-pull from repo) delete, d Archive a template submission branches List branches for a git repository refs List branches and tags (with the default branch) for a git repository search-refs Search branches and tags by name for a git repositoryOPTIONS: --help, -h show help
Browsing templates:
# List all templatespinata agents templates list# List featured templates onlypinata agents templates list --featured# Filter by categorypinata agents templates list --category ai# Get template detailspinata agents templates get ipfs-expert
Submitting templates:Your git repo must contain a valid manifest.json, a README.md, and a workspace/ directory. See Creating Templates for the full specification.submit, update, and validate share the --ref and --path flags:
OPTIONS: --ref string, -r string, --branch string, -b string Git ref to submit from (e.g. refs/heads/main, refs/tags/v1.0.0, or a bare branch name; default: main) --path string, -p string Subdirectory within the repo to use as the template root (for monorepos) --name string Override the template name from manifest.json --slug string Override the template slug from manifest.json (lowercase, hyphens only) --help, -h show help
--branch/-b are kept as aliases for --ref. You can pass a full ref (refs/heads/main, refs/tags/v1.0.0) or a bare branch name. Use --path to point at a subdirectory when your template lives inside a monorepo. --name/--slug are available on submit and update only.
# Validate your repo before submittingpinata agents templates validate https://github.com/user/my-agent-template# Validate a specific ref (branch or tag)pinata agents templates validate https://github.com/user/my-agent-template --ref refs/tags/v1.0.0# Validate a template that lives in a subdirectory (monorepo)pinata agents templates validate https://github.com/user/monorepo --path packages/my-agent# Submit the templatepinata agents templates submit https://github.com/user/my-agent-template# Submit from a specific branch with name/slug overridespinata agents templates submit https://github.com/user/my-agent-template \ --ref develop --name "My Agent" --slug my-agent
Discovering refs:
# List branches for a repopinata agents templates branches https://github.com/user/my-agent-template# List branches and tags (with the default branch)pinata agents templates refs https://github.com/user/my-agent-template# Search branches and tags by namepinata agents templates search-refs https://github.com/user/my-agent-template v1
Managing your submissions:
# List your submitted templatespinata agents templates mine# Update an existing submission (re-pull from repo)pinata agents templates update <template-id># Update with a new repo URL or refpinata agents templates update <template-id> --git-url https://github.com/user/new-repo --ref main# Archive a submissionpinata agents templates delete <template-id>
Browse and install skills from ClawHub, the community skills marketplace.
NAME: pinata agents clawhub - Browse and install skills from ClawHubUSAGE: pinata agents clawhub [command [command options]]COMMANDS: list, l Browse ClawHub skills get, g Get ClawHub skill details by slug install, i Install a ClawHub skill to your libraryOPTIONS: --help, -h show help
list options:
OPTIONS: --category string, -c string Filter by category --sort string, -s string Sort by: popular, newest, name --featured Show only featured skills --cursor string Pagination cursor --help, -h show help
Examples:
# Browse available skillspinata agents clawhub list# Browse featured skills, newest firstpinata agents clawhub list --featured --sort newest# Get skill details by slugpinata agents clawhub get clawdhub# Install a skill to your librarypinata 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]]COMMANDS: list, l List custom domains add, a Register a custom domain update, u Update a custom domain delete, d Remove a custom domainOPTIONS: --help, -h show help
add options:
OPTIONS: --subdomain string Subdomain name (e.g., 'myapp' for myapp.apps.pinata.cloud) --domain string Custom domain (e.g., 'api.example.com') --port int Target container port --protected Require authentication --help, -h show help
update options:
OPTIONS: --subdomain string New subdomain name --domain string New custom domain --port int New target port (default: 0) --protected Enable authentication --no-protected Disable authentication --help, -h show help
Examples:
# List domains for an agentpinata 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 domainpinata agents domains add <agent-id> --domain api.example.com --port 3000 --protected# Update domain portpinata agents domains update <agent-id> <domain-id> --port 8081# Disable authentication on a domainpinata agents domains update <agent-id> <domain-id> --no-protected# Remove domainpinata agents domains delete <agent-id> <domain-id>
NAME: pinata agents ports - Manage agent port forwardingUSAGE: pinata agents ports [command [command options]]COMMANDS: list, l List port forwarding rules set, s Set port forwarding rulesOPTIONS: --help, -h show help
Examples:
# List current port mappingspinata agents ports list <agent-id># Set port forwarding (port:pathPrefix format, up to 10 rules)pinata agents ports set <agent-id> 8080:/api 3000:/app# Clear all port forwarding rulespinata agents ports set <agent-id>
NAME: pinata agents versions - List available agent versionsUSAGE: pinata agents versions [options] [agent ID]OPTIONS: --help, -h show help
Example:
pinata agents versions <agent-id>
For agents on an engine that publishes versions per engine (such as Hermes), the output includes availableVersionsPerEngine (grouped by openclaw/hermes) alongside the agent’s current engine and version.
Authenticate with AI providers and store credentials as secrets for your agents.
NAME: pinata agents auth - Authenticate with a provider and store the credential as a secretUSAGE: pinata agents auth [options] [provider: anthropic, openai, openrouter, venice]OPTIONS: --oauth Use OAuth browser flow instead of API key (openai only) --help, -h show help
Supported Providers:
Provider
Secret Name
Options
anthropic
ANTHROPIC_API_KEY
-
openai
OPENAI_API_KEY or OPENAI_OAUTH_TOKEN
--oauth for Codex OAuth flow
openrouter
OPENROUTER_API_KEY
-
venice
VENICE_API_KEY
-
Examples:
# Store Anthropic API keypinata agents auth anthropic# Store OpenAI API keypinata agents auth openai# Authenticate with OpenAI via OAuth (for Codex CLI)pinata agents auth openai --oauth# Store OpenRouter API keypinata agents auth openrouter# Store Venice API keypinata agents auth venice