CLI: Setup & Scaffolding

Guided setup

Run the guided five-step onboarding flow to get started from scratch:

valet setup

Steps: (1) log in, (2) create or join an organization, (3) install the /valet skill for Claude Code, (4) scaffold a new agent project, (5) deploy and verify. Each step can be skipped if already completed — if you already belong to an org, step 2 sets your first org as the default and moves on automatically. Press Ctrl+C at any prompt to cancel.

$ valet setup
Welcome to Valet!
Let's get you set up.

Step 1 of 5: Log in
✓ Already logged in as alice@example.com

Step 2 of 5: Create your organization
What would you like to name your organization? acme
✓ Created org acme

Step 3 of 5: Install /valet skill for Claude Code
✓ Installed Valet skill to ~/.claude/skills/valet/SKILL.md

Step 4 of 5: Create your first agent
...

Step 5 of 5: Deploy
Creating agent... done, my-agent
Deploying... done, my-agent v1
Waiting for agent to start... done

Authentication

Log in to your Valet account and set your default organization:

valet auth login

Opens a browser window to authenticate. After login, the CLI fetches your organizations and always sets the default org to your earliest one — even if a default org is already configured. This ensures the local config stays in sync when you switch between environments or accounts. Check who you are logged in as with:

valet auth whoami

valet auth whoami verifies your session by attempting a token refresh, not just checking for a credentials file on disk. If the access token is expired and the refresh token is still valid, the CLI refreshes transparently and persists the new credentials. If both tokens are expired, the command exits 1 with:

Error: not logged in

When this happens, run valet auth login to re-authenticate. This ensures valet auth whoami always agrees with what the next RPC call would report.

Authentication via environment variable

The CLI also accepts a token via the VALET_API_TOKEN environment variable. When set to a non-empty value, it takes precedence over on-disk credentials — no valet auth login is required. The token is used verbatim for every RPC; the on-disk credential file and token refresh paths are bypassed entirely.

export VALET_API_TOKEN=<jwt>
valet auth whoami

When authenticated via VALET_API_TOKEN, valet auth whoami reports:

Authenticated via: VALET_API_TOKEN env var (service identity)

Default org and linked-project rendering remain intact — those are derived from config, not from the auth source. The generic valet connector uses an org-agent credential to inject VALET_API_TOKEN into every valet invocation inside an integration container.

• valet auth login and valet auth logout always operate on the on-disk credential file. If VALET_API_TOKEN is set when you run valet auth login, the file is written but the env var still wins for subsequent calls. Clear the env var to restore normal credential-file behavior.

Update the CLI

Update the Valet CLI to the latest version:

valet update

Uses the installation method that owns the running binary. Official direct installations download the latest release manifest and verify the archive before replacing the CLI. Homebrew installations continue to run brew upgrade valetdotdev/tap/valet. Unmanaged binaries are never modified; reinstall one with the official installer to enable self-updates.

Scaffold a new agent project

Create a new agent project directory without running the full setup flow:

valet new <name> [--dir <path>]

Creates <name>/ (or the path from --dir) containing SOUL.md, AGENTS.md, CLAUDE.md, a placeholder valet.yaml, skills/, and channels/. Edit SOUL.md to define your agent, fill in the manifest, then run valet agents create to deploy it.

• --dir — Directory to create the project in (default: ./<name>)

$ valet new my-agent
Created agent project my-agent

  my-agent/
    SOUL.md        Agent personality and behavior
    AGENTS.md      Conventions for coding agents
    CLAUDE.md      Points Claude Code at AGENTS.md
    valet.yaml     Manifest describing connectors and channels
    skills/        Custom skills (add .md files)
    channels/      Channel prompts (add .md files)