Seven commands cover everything a new user needs: discover, scaffold, start, look, share, diagnose, stop. Learn these and you can run a project end-to-end without ever opening the help screen.
Each entry: what the command does in one sentence, the minimum input
it needs, a copy-pasteable example, the output you should see, sibling
commands worth knowing, and the failure mode you'll hit first.
For the complete command surface (~230 commands across ~40 groups), see
cli/index.
asd help — list every commandPrints all available commands grouped by topic, with a one-line
description per command and a Total: N commands line at the bottom.
Run it any time you suspect this wiki is stale or you're guessing at
syntax.
Minimum input: none.
Example:
$ asd help
ASD CLI — https://github.com/asd-engineering/asd-cli
📋 Available Commands
📦 ac
ac install - Install shell completions (auto-detects shell, …)
…
📦 auth
auth status - Show authentication status
…
Total: 229 commands
For an interactive version with fuzzy search, type asd actions
(opens the command palette).
Most likely failure: the output mentions a command you don't have.
Run asd update to pull the latest CLI.
asd init — scaffold a projectCreates asd.yaml, a starter .env, and .gitignore entries in the
current directory. Run this once per new project.
Minimum input: be in the (empty or existing) project directory.
Example:
$ cd my-new-project
$ asd init
✓ Created asd.yaml from template
✓ Created .gitignore with .env and .asd exclusions
✓ Installing module binaries (caddy, codeserver, ttyd, …)
{"seeded":["ttyd","mitmproxy","hub","dbgate","codeserver"], …}
The generated asd.yaml is a starting point. Edit it to add your
project name, declare services, and define the up automation task
(what asd up will run).
Sibling commands:
| Command | When to use |
|---|---|
asd setup |
Same thing — init is the alias people remember. |
asd projects add . |
Register an existing asd project with the registry without scaffolding. |
asd env init |
Re-create .env from module templates only (skip asd.yaml). |
asd env sync |
Pull new keys from templates without losing your edits. |
Most likely failure: "Template file not found. Cannot scaffold
asd.yaml" — you're running a bare binary without the bundled module
templates. Reinstall via the official installer (install.sh /
install.ps1) which pulls the full distribution.
asd up — start the workspaceReads the automation.up task in asd.yaml and runs it. This is the
single "go" verb — it starts containers, dev servers, watchers,
anything your project defines.
Minimum input: an asd.yaml with an up (or other named) task in
its automation: section.
Example:
# asd.yaml (excerpt)
automation:
up:
- run: "docker compose up -d"
- run: "pnpm dev"
$ asd up
▶ docker compose up -d
Container my-app-db Started
Container my-app Started
▶ pnpm dev
✓ Server listening on http://localhost:3000
Flags worth knowing:
| Flag | Effect |
|---|---|
--task=<name> |
Run a different automation task (asd up --task=worker). |
--env=<file> |
Source a specific env file instead of .env. |
--dev / --prod |
Shortcut for --task=dev / --task=prod. |
Most likely failure: "No automation tasks defined in asd.yaml" —
add an automation: block. The error message shows a minimal example.
asd services — see what's runningDashboard view: one row per service, showing process status, tunnel
URL, web URL, and the local-host bind. Run it whenever you wonder
"what's actually live right now?".
Minimum input: be in a project directory.
Example:
$ asd services
[Services]
Name Process Tunnel Webserver Host
--------------------------------------------------------------------------
my-app 💻⚪ 🛜https://my-app.tn.example ✅my-app-route ✅http://127.0.0.1:3000
postgres 💻✅ ⚪ ⚪ ✅http://127.0.0.1:5432
Icons: 💻 process, 🛜 tunnel up, 🌀 tunnel starting, ⚪ not
applicable, ✅ healthy, ⛔ down.
By default this is an interactive TUI with keyboard navigation; the
above is what CI=true asd services (non-interactive) produces.
Sibling commands:
| Command | What it does |
|---|---|
asd (bare) |
Same as asd services. |
asd net |
Interactive network services TUI (richer view). |
asd urls |
Just the URLs, no status. |
Most likely failure: empty list. Either no services are registered
(run asd net apply after editing manifests) or asd isn't seeing
your project (check asd projects).
asd urls — the public + local URLsPrints the active URLs from the registry: the Caddy reverse-proxy URL,
the public tunnel URL (if exposed), and the direct localhost URL.
Optimised for piping into other tooling.
Minimum input: a workspace that's been started.
Example:
$ asd urls
🔗 Active workspace URLs:
my-app
caddy: https://my-app.localhost
tunnel: https://my-app-xyz1.eu2.tn.example.com
direct: http://127.0.0.1:3000
postgres
direct: postgres://localhost:5432
Sibling commands:
| Command | What it does |
|---|---|
asd net urls |
Same data, scoped to the net group. |
asd net open <service> |
Open a service's URL in the browser. |
Most likely failure: "No services in registry. Run asd run dev
or asd net apply first." You haven't started anything yet, or no
service has been registered.
asd expose <port> — tunnel a port in five secondsThe shortest possible path from localhost:<port> to a public HTTPS
URL. No asd.yaml automation, no net.manifest.yaml, no edits.
Minimum input: a process listening on the given port and a working
auth credential set (asd auth status ✓).
Example:
$ # Terminal A: dev server
$ python3 -m http.server 3000
$ # Terminal B: expose it
$ asd expose 3000
✓ Exposed http://localhost:3000 → https://3000-xyz1.eu2.tn.example.com
Flags worth knowing:
| Flag | Effect |
|---|---|
<port> <name> |
Use <name> as the subdomain instead of the port number. |
--subdomain <s> |
Set the subdomain explicitly. |
--name <s> |
Name the service in the registry. |
--auth=basic |
Force basic auth on the tunnel. |
--auth=none |
Disable auth on the tunnel. |
--local-only |
Skip the public tunnel — Caddy route only. |
Sibling commands:
| Command | What it does |
|---|---|
asd expose list |
Show currently exposed services + orphan tunnels. |
asd expose stop <name\|port> |
Stop a specific exposure. |
asd expose auth |
Show basic-auth credentials for exposed services. |
asd expose cleanup |
Drop stale entries from the registry. |
Most likely failure: asd auth status reports no/invalid
credentials. Run asd login (OAuth) or asd login key <KEY>
(headless) first.
asd doctor — diagnostics in one commandSystem-wide health check: Docker daemon, Caddy admin reachability,
restarting containers, stale compose-project clones, env drift, and
~6 more probes. Run it the moment something starts going wrong.
Minimum input: none.
Example:
$ asd doctor
asd doctor — 6 probe(s) in 301ms — overall: ❌ fail
✅ Docker daemon linux/x86_64, server 29.4.3
⚠️ Stale clones duplicate compose-project clones present (190ms)
⚠️ 3 compose project(s) don't match any registered asd project
asd-vs100
asd-t3352
asd-vs101
✅ Restarting containers no containers restarting
❌ Caddy config caddy admin /config/ unreachable (7ms)
Each probe shows status (✅/⚠️/❌), one-line summary, and (on warning
or failure) detail lines that often quote the exact command to fix it.
Sibling commands:
| Command | What it does |
|---|---|
asd doctor logs |
Tail the persistent diagnostics log. |
asd doctor logs clear |
Truncate the log. |
Most likely failure: asd doctor itself returns ❌ overall —
that's the point. Walk the detail lines top to bottom; most fixes
are one-liners (asd caddy start, docker start <container>,
asd net apply).
asd down — stop everythingWhen asd up is your "go", asd down is your "stop". Tears down the
workspace per the automation.onDown declarations in asd.yaml.
$ asd down
▶ Stopping workspace
✓ tunnels stopped (3)
✓ services stopped (2)
✓ caddy stopped
asd down list shows the teardown manifest before you run it.
asd down <task> runs just one task's teardown.
cli/index — every group + key commands.learn/01-hello-world.asd up is actually orchestrating: concepts.