Valet CLI
The Valet CLI manages the full lifecycle of artifacts, apps, agents, integrations, channels, skills, environment variables, and organizations.
Installation
curl -fsSL https://valet.dev/install.sh | shAuthentication
You must be logged in before any other command will work:
valet auth loginCheck auth status:
valet auth whoamiThe one exception is anonymous artifact publishing — valet sites create --anonymous needs no account at all.
Help & Discovery
valet help prints a flat list of every runnable command and subcommand at a glance — including deeply nested subcommands like channels catalog get. Use it to discover commands without running each group's help separately.
For flag details on a specific command, use valet <command> --help. Subcommand help still uses the standard Cobra rendering with full flag descriptions.
valet help # Flat list of all commands and subcommands
valet <command> --help # Subcommand help (flags and options)
valet topics # List help guides
valet topics <name> # Read a specific guide
valet completion --help # Shell completion setup
valet version # Print CLI version
valet update # Update the CLI to the latest versionExample output from valet help:
Valet runs your agents
Commands:
agents List agents
agents create [name] Create an agent and deploy it
agents destroy <name> Destroy an agent
agents info [name] Show agent details
agents link <name> Link the current directory to an agent
agents rename <new-name> Rename an agent
apps List apps
apps create [name] Create an app
apps destroy <name> Destroy an app
apps link <name> Link the current directory to an app
auth login Log in to Valet
auth logout Log out of Valet
auth whoami Show the current user
channels List channels
channels attach <channel-name> Attach an org channel to an agent
channels catalog List channel catalog entries
channels catalog get <name> Show catalog entry details
channels create Create a channel
channels create cron [name] Create a cron channel
channels create email [name] Create an email channel
channels create heartbeat [name] Create a heartbeat channel
channels create mcp [name] Create an MCP channel
channels create slack [name] Create a Slack channel
channels create telegram [name] Create a Telegram channel
channels create webhook [name] Create a webhook channel
channels destroy <name> Destroy a channel
channels detach <alias> Detach a channel from an agent
channels info <name> Show channel details
channels reauthorize <name> Mint a fresh authorization URL for a channel
channels slack Manage Slack activity levels
channels slack add <#conversation> Add the agent's bot to a Slack conversation
channels slack set <#conversation> <level> Set one conversation's activity level
channels slack set-default <level> Set the channel default activity level
channels token list <channel> List tokens on an MCP channel
channels token mint <channel> <token-name> Mint a bearer token for an MCP channel
channels token revoke <channel> <token-name> Revoke a token on an MCP channel
connectors List connectors
connectors attach <connector-name> Attach an org connector to an agent
connectors catalog List connector catalog entries
connectors catalog get <name> Show catalog entry details
connectors create Create a connector
connectors create command <name> Create a command connector
connectors create mcp-server <name> Create an MCP server connector
connectors destroy <name> Destroy a connector
connectors detach <alias> Detach a connector from an agent
connectors info <name> Show connector details
connectors reauthorize <name> Restart the OAuth flow for a connector
console Start an interactive console session
deploy Deploy an agent
drafts List agent drafts
drafts checkout <draft_id> Clone the draft branch and print the working directory path
drafts create Open a new draft for an agent
drafts discard <draft_id> Delete a draft without publishing
drafts info <draft_id> Show draft detail
drafts publish <draft_id> Promote a draft to main
drafts push <draft_id> Ship local files to a draft branch
drafts validate [draft-id] Verify the draft's valet.yaml parses against the manifest schema
drains List log drains
drains create <endpoint> Create a log drain
drains destroy <endpoint> Destroy a log drain
drains info <endpoint> Show drain details
emails List email mailboxes
emails create Create an email mailbox and mint its address
emails destroy <address> Destroy an email mailbox
emails info <address> Show mailbox details
emails quarantine List quarantined messages
emails quarantine release <message-id> Release a quarantined message
emails threads List a mailbox's threads
emails threads info <message-id> Show a thread by its root Message-ID
env List env vars
env set <NAME=VALUE>... Set env vars
env unset <NAME> Unset an env var
exec [NAME[,NAME...] --] command [args...] Run a command with env vars injected
logs Show recent agent logs
manifests create [name] Generate a valet.yaml for an existing agent
manifests validate [path] Validate a manifest file
memories List memories
memories set <KEY=VALUE> Set a memory
memories unset <KEY> Unset a memory
new <name> Scaffold an agent project
orgs List organizations
orgs create <name> Create an organization
orgs destroy <name> Destroy an organization
orgs info <name> Show organization details
orgs invite <name> <email> Invite a member to an organization
orgs join <code> Join an organization using an invitation code
orgs leave <name> Leave an organization
orgs members <name> List members and invitations for an organization
orgs remove <name> <email> Remove a member from an organization
orgs revoke <name> <email> Revoke a pending organization invitation
orgs set-default <name> Set the default organization
ps List processes for an agent
ps restart Restart all processes for an agent
ps scale <process>=<value>... Scale processes for an agent or app
releases List releases for an agent
releases files [<name>] List files in the deployed release
releases read [<name>] <path> Print a file from the deployed release
run <prompt> Send a prompt to an agent and stream the response
sessions List or show sessions
sessions delete <id> Delete a session
sessions info <id> Show session details
setup Set up Valet with guided onboarding
sites List sites
sites access <name> [public|private|password] Show or set a site's visibility
sites claim [name] Claim an anonymous site into an org
sites create [name] Create a site
sites destroy [name] Destroy a site
sites download <name> [dir] Download a deployed site's files
sites info [name] Show site details
sites link <name> Link the current directory to a site
skills List configured agent and org skills
skills attach <source> Attach a skill to an agent
skills catalog List curated skill catalog entries
skills detach <source-or-name> Detach a skill from an agent
skills info <name> Show org skill details
topics agent-lifecycle Agent creation, linking, and deployment
topics channels Channels and sessions
topics connectors-overview Connectors (MCP and command)
topics getting-started Getting started with Valet
topics resolution How Valet resolves agents and orgs
update Update the Valet CLI to the latest version
version Print the CLI version
Run 'valet <command> --help' for details on a specific command.
Run 'valet completion --help' for shell completion setup.Core Concepts
- Artifact — A directory of static files served over HTTPS at a generated hostname. Create an artifact, deploy it with
valet deploy, and control who can view it withvalet sites access. - App — A Procfile application built with buildpacks and served over HTTPS. Like an artifact, but with running processes that can be scaled per process type.
- Agent — An AI agent defined by a
SOUL.mdfile in a project directory. Agents are deployed as versioned releases. - Organization — A team that shares artifacts, apps, agents, integrations, channels, skills, and env vars. Members collaborate on org-scoped resources.
- Integration — An MCP server or CLI tool that provides capabilities to agents. Types:
mcp-server(MCP tools via client) andcommand(CLI with secret injection). - Channel — A message entry point for agents. Types:
webhook,slack,telegram,email,mcp,heartbeat,cron. - Skill — A versioned bundle of instructions (a
SKILL.mdplus supporting files) that an agent loads at deploy time, attached from the curated catalog or an org snapshot. - Env var — A named value scoped to an org or agent. Two kinds: secret (the default — encrypted credentials the agent can use but never see) and plain (configuration delivered to the agent's environment). Referenced using
{{NAME}}syntax in integration and channel configurations. - Route — A stable (host, path) handle bound to an artifact, app, or channel. Routes decouple public URLs from the entity that serves them. Product commands manage route changes as part of resource operations such as rename and destroy.
- Catalog — Valet-curated library of well-known integration, channel, and skill definitions. Add from the catalog instead of configuring from scratch.
- Shared resources — Org-scoped resources can be attached to agents. The three layers are: catalog (Valet-curated definitions), org resource (configured instance), and agent attachment (wired to an agent).
Agent Project Structure
my-agent/
SOUL.md # Agent personality and behavior (required)
valet.yaml # Manifest describing connectors and channels
channels/ # Channel prompts
my-channel.md # Prompt for messages on "my-channel"
skills/ # Agent skills
my-skill/
SKILL.md
mcp/ # Tools exposed by an MCP channel
my-tool.md
.valet/
config.json # Created by link/create (auto-managed)