Skip to main content
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.

list

create

--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:
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.

get

The response includes the agent’s engine so you can tell OpenClaw, Hermes, and other enabled engines apart.

delete

restart

logs

chat

Start an interactive chat session with an agent. Supports multiple output modes for different use cases, and works across supported agent engines.
Output Modes: Examples:

exec

Execute a command inside an agent’s container.
Examples:

files

Read files from an agent’s container.
Examples:

devices

Manage device pairing for agents (used for mobile/external device connections).
Examples:

skills

create options:
Examples:

secrets

create options:
Examples:

channels

configure options:
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:

snapshots

Examples:

tasks

create

update

Scoping skills to a task: create and update accept --skill (repeatable) to make specific skill CIDs available only while the task runs:

templates

Browse and manage agent templates. Includes browsing published templates and submitting your own from a GitHub/GitLab repository.
Browsing templates:
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:
--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.
Discovering refs:
Managing your submissions:

clawhub

Browse and install skills from ClawHub, the community skills marketplace.
list options:
Examples:

domains

Manage custom domains for your agents (beta feature).
add options:
update options:
Examples:

ports

Manage agent port forwarding rules.
Examples:

config

Manage agent openclaw configuration.
Examples:

update

Manage openclaw version updates.
apply options:
Examples:

versions

List available agent image versions.
Example:
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.

engines

List the agent engines enabled for the current deployment. Use this to discover which values are valid for agents create --engine.
Example:
Returns the enabled engines, each with an id (the value you pass to --engine) and a human-readable label:

auth

Authenticate with AI providers and store credentials as secrets for your agents.
Supported Providers: Examples:

feedback

Submit feedback or a feature request from the terminal.
Example: