Skip to main content
The hud link command connects a local directory to an existing HUD platform environment, similar to vercel link for Vercel projects.

​
Usage

hud link [DIRECTORY] [OPTIONS]

​
Arguments

​
directory
string
default:"."
Directory to link

​
Options

​
--id
string
Environment ID to link to. If not provided, shows an interactive list. Short: -i
​
--yes
boolean
default:"false"
Skip confirmation prompts. Short: -y

​
Prerequisites

Requires HUD_API_KEY:
hud set HUD_API_KEY=your-api-key

​
What It Does

1

Check Existing Link

Checks if .hud/deploy.json already exists and prompts to overwrite if so
2

Select Environment

If --id not provided, fetches your environments and shows an interactive selection
3

Verify Access

Confirms you have access to the specified environment
4

Create Link

Creates .hud/deploy.json with the registry ID

​
Examples

​
Interactive Selection

hud link

# Output:
# Your environments:
#   1. browser-env v0.1.3 (abc123...)
#   2. terminal-env v0.2.0 (def456...)
#   3. api-server v1.0.0 (ghi789...)
# 
# Select environment number (or paste full ID): 1

# Link to specific environment by ID
hud link --id abc123-def456-...

# Link a specific subdirectory
hud link environments/browser --id abc123...

​
Use Cases

If you accidentally deleted .hud/deploy.json: 
# Find your environment on hud.ai, copy the ID
hud link --id your-environment-id

​
Working on Multiple Machines

# On new machine, link to existing environment
git clone your-repo && cd your-repo
hud link
# Select your environment from the list

​
Switching Environments

# Unlink current
rm .hud/deploy.json

# Link to different environment
hud link --id different-environment-id
After linking, .hud/deploy.json contains: 
{
  "registryId": "abc123-def456-...",
  "version": "0.1.3"
}
The .hud/ directory should typically be added to .gitignore as it contains machine-specific linking info.

​
See Also