CLI Command Reference | ASD Documentation

Quick Reference

The most common commands you will use day-to-day:

Command	Description
`asd init`	Initialize project workspace
`asd run <task>`	Run automation task from asd.yaml
`asd expose <port>`	Expose a local port with an HTTPS tunnel
`asd login`	Authenticate for tunnel access (OAuth)
`asd logout`	Sign out and clear credentials
`asd net`	Open the interactive network dashboard
`asd terminal`	Manage the web terminal
`asd code`	Manage VS Code server
`asd database`	Manage the database UI
`asd up`	Auto-discover and run startup task (up/dev/start)
`asd update`	Update ASD CLI to the latest version
`asd token create`	Create tunnel credentials
`asd vault`	Manage encrypted secrets
`asd auth status`	Check authentication status

Core Commands

asd init

Initialize a project workspace with configuration files and helper binaries.

asd init              # Interactive setup with prompts
asd init --yes        # Accept all defaults (non-interactive)
asd init --skip-binaries  # Skip downloading helper binaries

This command creates the asd.yaml configuration file, sets up the .asd/workspace/ directory, downloads helper binaries (Caddy, ttyd, code-server), generates a .env file from the project template, and optionally discovers services already running on your machine.

asd run

Run an automation task defined in your project’s asd.yaml. This is the simplest way to start your development environment.

asd run dev           # Run the 'dev' task
asd run prod          # Run the 'prod' task
asd run               # List available tasks

Tasks are defined in the automation: section of your asd.yaml:

automation:
  dev:
    - run: "pnpm dev"
      background: true
  prod:
    - run: "pnpm build && pnpm preview"
      background: true

Options:

--follow or -f — Follow logs after starting the task
--json — Output in JSON format for scripting

asd up

Shortcut for asd run that auto-discovers a startup task. ASD looks for tasks named up, dev, or start (in that order) and runs the first one it finds.

asd up                # Run the first matching task: up, dev, or start

This is the fastest way to bootstrap your development environment when your asd.yaml defines a conventional task name. Equivalent to running asd run up (or asd run dev, etc.) manually.

asd update

Update ASD CLI to the latest version.

asd update           # Update to latest release
asd update --check   # Check for updates without installing
asd update --force   # Force reinstall even if already up-to-date

asd login

Authenticate with the ASD platform to get tunnel credentials.

asd login

Running asd login opens your default browser for OAuth authentication. After you sign in, the CLI receives your credentials and stores them locally. On first login, ASD automatically creates an Ed25519 SSH key and registers it with your account.

If no browser is available (SSH sessions, CI runners, containers), ASD falls back to a device code flow. You see a short code like ABCD-EFGH and a URL. Open the URL on any device, enter the code, and the CLI completes authentication.

Expected output:

✅ Successfully logged in as you@example.com
🔐 SSH key created and registered

If you are already logged in, asd login tells you so:

✅ Already logged in as you@example.com
ℹ️ Use 'asd logout' to sign out first

Credentials are stored at:

Platform	Path
Linux	`~/.config/asd/tunnel/credentials.json`
macOS	`~/Library/Application Support/asd/tunnel/credentials.json`
Windows	`%APPDATA%/asd/tunnel/credentials.json`

For quick testing without an account, use ephemeral tokens instead — see the API Reference for details.

asd logout

Sign out and clear stored credentials.

asd logout

asd env-init

Manage environment variables in your .env file.

asd env-init              # Merge new variables with existing .env
asd env-init --override   # Replace the entire .env file

Expose Commands

Expose local services to the internet with HTTPS tunnels. This is one of the most-used features of ASD.

asd expose

Expose a local port instantly with a public HTTPS URL.

asd expose 3000                    # Basic exposure
asd expose 3000 --name myapp       # Named tunnel (sets URL prefix)
asd expose 3000 --local-only       # Local Caddy routing only, no tunnel
asd expose 3000 myapp --direct     # Direct tunnel, bypass Caddy

Options:

Option	Description
`--name <name>`	Set a name prefix for the tunnel URL
`--local-only`	Route locally via Caddy without creating a tunnel
`--direct`	Create a direct tunnel, skipping the Caddy proxy

After running, you get multiple access URLs:

Local:  http://localhost:3000
Caddy:  http://myapp.localhost
Tunnel: https://myapp-abc123.eu1.tn.asd.engineer

The --name option sets the URL prefix. The full tunnel URL follows the pattern <name>-<client-id>.eu1.tn.asd.engineer.

asd expose list

List all currently exposed services with their tunnel URLs, status, and uptime.

asd expose list          # List services in current project
asd expose list --all    # List services across all projects
asd expose list --json   # Output in JSON format for scripting

Options:

Option	Description
`--all`	Show services from all ASD projects, not only the current one
`--json`	Output in JSON format (includes ports, URLs, PIDs, and uptime)

Example output:

myapp
    Port:     3000
    Local:    http://myapp.localhost
    Tunnel:   https://myapp-abc123.eu1.tn.asd.engineer
    Status:   Online
    Uptime:   2h 15m

asd expose stop

Stop an exposed service by name or port number.

asd expose stop myapp    # Stop by name
asd expose stop 3000     # Stop by port

Network Commands

Network management via an interactive terminal UI (TUI) and supporting subcommands.

asd net

Open the interactive network dashboard. This gives you a live view of all services, their health status, and tunnel URLs.

asd net

Keyboard controls:

Key	Action
`Tab`	Cycle through tabs (Services, Projects, Logs)
`Enter`	Open actions menu for the selected service
`Ctrl+R`	Refresh health checks
`Ctrl+Q`	Quit
Arrow keys	Navigate the service list

asd net apply

Apply network configuration from your asd.yaml to start Caddy routes and tunnels.

asd net apply              # Apply all configuration
asd net apply --caddy      # Start the Caddy reverse proxy only
asd net apply --tunnel     # Start tunnels for configured services only
asd net apply --ids svc1,svc2  # Apply specific services by ID

asd net refresh

Re-run service detection and health checks.

asd net refresh

asd net discover

Scan for running services on your machine and register them in the network dashboard.

asd net discover

asd net expose

Manage tunnels for individual services or all services at once.

asd net expose start <service-id>    # Start tunnel for one service
asd net expose start --all           # Start tunnels for all public services
asd net expose stop <service-id>     # Stop tunnel for one service
asd net expose stop --all            # Stop all tunnels
asd net expose reset                 # Kill all tunnels and clear state

Other net subcommands

asd net start <service-id>    # Start a service
asd net stop <service-id>     # Stop a service
asd net open <service-id>     # Open service URL in browser
asd net remove <service-id>   # Remove service from registry
asd net clean                 # Remove stale registry entries
asd net reset                 # Full registry reset

Service Commands

ASD bundles several built-in services for remote development. Each service has an interactive menu (run the bare command) and direct start/stop subcommands.

asd terminal

Manage the web terminal powered by ttyd. Gives you a full shell session accessible from any browser.

asd terminal          # Interactive menu with status and URLs
asd terminal start    # Start the web terminal
asd terminal stop     # Stop the web terminal

Requires TTYD_USERNAME and TTYD_PASSWORD to be set in your .env file. See the Built-in Services page for full configuration details.

asd code

Manage the VS Code server powered by code-server. Run a full VS Code IDE in your browser.

asd code          # Interactive menu
asd code start    # Start VS Code server
asd code stop     # Stop VS Code server

asd database

Manage the database UI powered by DbGate. Browse schemas, run queries, and manage data visually.

asd database          # Interactive menu
asd database start    # Start database UI
asd database stop     # Stop database UI

asd inspect

Network traffic inspector powered by mitmproxy. Currently in alpha.

asd inspect          # Interactive menu
asd inspect start    # Start mitmproxy
asd inspect stop     # Stop mitmproxy

Caddy Commands

Manage the built-in Caddy reverse proxy that provides local routing and HTTPS for your services.

asd caddy start      # Start Caddy reverse proxy
asd caddy stop       # Stop Caddy
asd caddy restart    # Restart Caddy
asd caddy config     # Show current Caddy configuration

Caddy handles path-based routing so you can access all services under a single domain (e.g., asd.localhost/asde/ttyd/, asd.localhost/asde/codeserver/).

Auth Commands

Manage your authentication credentials for tunnel access.

asd auth status       # Show current authentication status
asd auth credentials  # View all credential sources and their status
asd auth whoami       # Show current user email, client ID, and org ID
asd auth refresh      # Refresh an expired authentication token
asd auth switch       # Switch between credential profiles

Token Commands

Manage tunnel credentials for your account.

asd token             # List all tokens (same as asd token list)
asd token create      # Create new ephemeral tunnel credentials
asd token verify      # Verify current tunnel credentials are valid
asd token list        # List all tunnel tokens with status
asd token use <name>  # Switch to a specific token by name or ID

asd token create generates ephemeral tunnel credentials and saves them to your .env file (or ~/.local/share/asd/credentials.env when not in a project directory). Use asd token verify to check if your current credentials are still valid.

Options for asd token create:

Option	Description
`--scope cicd`	Create a CI/CD-scoped token (bypasses SSH auth mode restriction)
`--json`	Output raw JSON instead of formatted text

Tunnel Authentication Methods

Ephemeral tokens require no account and are valid for 5 minutes. Ideal for quick testing:

curl -X POST https://asd.engineer/functions/v1/create-ephemeral-token

Tunnel tokens are created from your ASD dashboard and are meant for CI/CD and long-running sessions:

export ASD_TUNNEL_TOKEN=your-token
export ASD_TUNNEL_USER=your-user-id
asd expose 3000

For full API details, see the API Reference.

Vault Commands

Manage encrypted secrets backed by Supabase Vault (pgsodium). All vault commands are currently in Alpha and require authentication via asd login. For full details, see the Vault documentation.

asd vault set <name> [value]    # Store a secret (or use --stdin / --file)
asd vault get <name>            # Print decrypted value to stdout
asd vault list                  # List secret metadata (names, categories)
asd vault delete <name>         # Soft-delete a secret
asd vault inject <tpl> <out>    # Replace asd:// references in a template file
asd vault run --env-file <tpl> -- <cmd>  # Run a command with secrets as env vars

Options for asd vault set:

Option	Description
`--stdin`	Read value from standard input
`--file <path>`	Read value from a file
`--category <cat>`	Group the secret under a category
`--description <desc>`	Add a human-readable description
`--scope org`	Store as an organisation-scoped secret (default: `user`)

Vault availability depends on your subscription plan. The Developer plan includes 10 secrets, Pro includes 50, and Scale includes 200.

Key Commands

Manage SSH keys used for tunnel authentication. Keys are created automatically during asd login, but you can also manage them manually.

asd key               # Interactive key management menu
asd key list          # List registered SSH keys with fingerprints
asd key upload        # Upload a new SSH public key
asd key revoke        # Revoke a registered SSH key

SSH keys authenticate tunnel connections. When you run asd login, ASD generates an Ed25519 key and registers it with your account automatically. Use the key commands when you need to manage keys across multiple machines or rotate keys manually.

For the API equivalent, see the SSH Keys section in the API Reference.

GitHub Integration

Run remote development sessions using GitHub Actions runners. This is in beta.

asd gh                # Show GitHub integration menu
asd gh setup          # Install GitHub workflow files in your repo
asd gh terminal       # Start a remote terminal session in GitHub Actions
asd gh list           # List recent workflow runs
asd gh runs           # Show active workflow runs
asd gh active         # Check for active sessions
asd gh stop           # Stop a running session
asd gh login          # Configure GitHub authentication

This feature lets you debug CI failures interactively by opening a live terminal into a GitHub Actions runner.

Logs

View logs for any ASD-managed service.

asd logs caddy      # Caddy reverse proxy logs
asd logs tunnel     # Tunnel connection logs
asd logs ttyd       # Web terminal logs

All logs are stored in .asd/workspace/logs/.

Global Options

Available for all commands:

Option	Description
`--help`	Show help text for any command
`--version`	Show installed ASD CLI version

Environment Variables

Control ASD behavior with these environment variables, set in your .env or shell:

General settings:

Variable	Description
`ASD_DEBUG=1`	Enable debug logging
`ASD_VERBOSE=1`	Enable verbose output
`ASD_BIN_LOCATION`	Where to store binaries: `global` (default) or `workspace`

Tunnel credentials:

Variable	Description
`ASD_TUNNEL_TOKEN`	Tunnel authentication token
`ASD_TUNNEL_USER`	Tunnel username / client ID
`ASD_TUNNEL_HOST`	Server hostname (optional, auto-detected)
`ASD_TUNNEL_PORT`	Server SSH port (optional, default 2223)

Service credentials:

Variable	Description
`ASD_BASIC_AUTH_USERNAME`	Basic auth username for Caddy routes
`ASD_BASIC_AUTH_PASSWORD`	Basic auth password for Caddy routes
`TTYD_USERNAME`	Web terminal login username
`TTYD_PASSWORD`	Web terminal login password
`TTYD_PORT`	Web terminal port (auto-assigned if not set)
`ASD_CODESERVER_AUTH`	VS Code server auth mode: `none` or `password`
`ASD_CODESERVER_PASSWORD`	VS Code server password
`ASD_CODESERVER_PORT`	VS Code server port (auto-assigned if not set)

Command Maturity Status

Not all commands are at the same level of maturity. The table below shows what you can rely on in production versus what is still experimental.

Status	Meaning
Production	Fully tested, stable API
Stable	Works reliably, minor changes possible
Beta	Functional but may have rough edges
Alpha	Experimental, expect changes

Command	Status
`asd init`	Production
`asd run`	Stable
`asd net`	Production
`asd net apply`	Production
`asd expose`	Stable
`asd login` / `asd logout`	Stable
`asd auth status` / `asd auth credentials`	Beta
`asd terminal`	Stable
`asd code`	Stable
`asd database`	Stable
`asd caddy`	Production
`asd update`	Stable
`asd env-init`	Stable
`asd token`	Beta
`asd key`	Beta
`asd vault`	Alpha
`asd logs`	Beta
`asd gh`	Beta
`asd inspect`	Alpha

Related Guides

Getting Started — Install ASD and expose your first service
Understanding Tunnels — How HTTPS tunnels work, URL format, and tunnel lifetime
Configuration Reference (asd.yaml) — Full project configuration reference
Security and Authentication — Secure your exposed services with Basic Auth and tokens