Connect a Workspace

You created a workspace on the web — Pad Cloud or your own self-hosted Pad — and now you want to manage it from your terminal: run pad item create, hand the /pad agent skill to your AI tooling, or just have a .pad.toml link the directory so subsequent commands “just work.” This page covers the one-line connect flow.

TL;DR

From your project directory, run:

pad init --url https://app.getpad.dev --workspace my-workspace

…replacing https://app.getpad.dev with your Pad server’s URL and my-workspace with your workspace’s slug. Pad will:

  1. Configure the CLI to talk to that server (saved to ~/.pad/config.toml).
  2. Authenticate in your browser (skipped if you’re already signed in to that server).
  3. Link this directory by writing a .pad.toml file with the workspace slug.
  4. Install the /pad skill for any AI coding agent it detects (Claude Code, Cursor, Windsurf, Codex, Copilot, Amazon Q, Junie).

You only need to do this once per project.

Where to find your server URL and workspace slug

The web UI surfaces both for you. Inside the workspace, click your avatar (top right) and choose Connect a project… — the dialog pre-fills the exact pad init … command for your environment, ready to copy.

If you’d rather build it by hand:

  • Server URL is the origin you visit in the browser:
    • Pad Cloud: https://app.getpad.dev
    • A team self-hosted instance: whatever URL your operator gave you (e.g. https://pad.acme.internal)
    • A local server: http://localhost:7777 (or whatever port you bound)
  • Workspace slug is the slug in the URL when you’re inside a workspace: app.getpad.dev/{username}/{workspace-slug}. The slug is the workspace’s name lowercased and hyphenated.

Prerequisites

If you haven’t installed pad yet, do that first. The CLI is the same binary as the server — install once and you have both.

# macOS & Linux (Homebrew)
brew install PerpetualSoftware/tap/pad

# Docker
docker run -p 127.0.0.1:7777:7777 -v pad-data:/data ghcr.io/perpetualsoftware/pad

For Windows, download a pre-built binary from the releases page. For all install paths see Installation.

What .pad.toml does

pad init writes a small file at the root of your project:

workspace = "my-workspace"

The pad CLI walks up from the current directory looking for .pad.toml, so any pad command you run inside the project knows which workspace to operate against. The /pad agent skill uses the same detection so AI agents pick up the right workspace automatically.

Should you commit .pad.toml? Generally yes. Committing it means anyone who clones the repo and has the pad CLI installed can run pad item list, pad project dashboard, etc. without first re-running pad init. The file contains no secrets — only the workspace slug. If your project is public and you’d rather not advertise the slug, add .pad.toml to .gitignore instead.

Switching between Pad Cloud, a remote server, and local

You can have multiple Pad servers and bounce between them with --url:

# This directory points at a workspace on Pad Cloud
pad init --url https://app.getpad.dev --workspace cloud-project

# A different directory points at a self-hosted instance
cd ../other-project
pad init --url https://pad.acme.internal --workspace acme-roadmap

# Yet another directory uses your local pad server (default if --url is omitted)
cd ../personal-notes
pad init

Each pad init saves the connection mode to ~/.pad/config.toml — that’s the global default for the pad CLI on this machine. The per-project .pad.toml pins the workspace slug, but it does NOT pin the server URL. So if you re-run pad init --url … somewhere else and switch the global server, commands in your other directories will start resolving their .pad.toml slug against the new global server.

If you keep workspaces on multiple servers and the same slug exists on more than one, either re-run pad init --url <server> --workspace <slug> inside the project (which updates both the global server and the local link), or pass --url as a per-command override:

pad --url https://pad.acme.internal item list

Troubleshooting

“Workspace ‘X’ not found on https://…”

The slug doesn’t exist on that server, or your account doesn’t have access to it. After authenticating, run pad workspace list to see the workspaces you can connect to.

“This directory is already linked to workspace ‘Y’; refusing to relink to ‘X’”

There’s already a .pad.toml in this directory or one of its parents pointing to a different workspace. To change it, edit or remove that file and re-run pad init. (pad init refuses to silently clobber an existing link.)

“Pad is not configured. Run ‘pad auth configure’ first…”

You ran pad init without --url on a fresh machine that has no ~/.pad/config.toml yet, in a non-interactive context (CI, scripts). Pass both --url <server> and --workspace <slug> together to make pad init work without prompts — that combination is the canonical non-interactive cold-start.

“Failed to connect to server at …”

The URL is wrong, your network can’t reach it, or the server is down. Check the URL in your browser; if your team self-hosts, ask whoever runs the server.

My CLI command worked, but the web UI still shows the connect banner

The banner refreshes when you open and close the Connect a project… dialog, or on a page reload. Either action will flip the banner off once you’ve created your first item from the CLI.

What’s next

  • CLI Reference — every pad subcommand
  • Agent Integration — how the /pad skill works in Claude Code, Cursor, and other AI coding tools
  • Web UI Guide — keyboard shortcuts and power-user features
  • Configuration — what lives in ~/.pad/config.toml and how to manage multiple servers