bdy distro route create

$bdy distro route create|add [options] <identifier>

Add a route to a distribution Required scopes: DISTRIBUTION_WRITE

ARGUMENTS

identifier

Human-readable ID of the distribution (required)

OPTIONS

--context <name>

Connection and scope context: default, git, link or a saved name. Overrides the globally active context for this invocation.

--examples

Show only examples; with this flag --format accepts text, json or jsonl

--verbose

Show REST API requests, responses, timing and retries on stderr

-w, --workspace <domain>

Workspace URL handle. Can be set via variable: BUDDY_WORKSPACE

-p, --project <name>

Project name. Can be set via variable: BUDDY_PROJECT

--scope <scope>

Force scope (WORKSPACE, PROJECT). By default calculated by provided options and environmental variables (--project, BUDDY_PROJECT, linked project)

-t, --type <type>

Type of the route. Allowed: DIRECT_PROXY (default), CACHED_PROXY, REDIRECT, CLOAKING

-s, --subdomain <subdomain>

Optional sub-name prepended to --domain (e.g.

-d, --domain <domain>

Zone for the route — pass the WHOLE string from bdy domain ls (e.g. "example.com" or "my-app.example.dev"). Do NOT split a multi-level zone into subdomain+domain; the entire bought/claimed string is one zone and goes here as-is. Use --subdomain only to route a sub-name within this zone

--path <path>

Path of the route

--note <note>

Note of the route

--agent-note <note>

Note of the route for AI agents; stored as agent_note and meant to be read before acting on the resource

--target <targets...>

Target of the route (can be used multiple times). Format: "region=default,url=https://example.com,artifact=artifact:version,sandbox=sandbox:endpoint" To use "," in value use , For external url target use url (required), region (optional) For artifact target use artifact (required), region (optional) For sandbox target use sandbox (required), region (optional) Region can be Default, NorthAmerica, Europe, Asia, Oceania, SouthAmerica, Africa, Antarctica or two letter country name If no region is specified or default is used, the target is used as the fallback for all locations. Default region is mandatory

--format <text|json>

Output format: json, text. JSON CLI errors: {error:{code,message,hint}}, exit 1. Default: text (choices: "text", "json")

-h, --help

display help for command

Documentation for bdy v1.25.20

Last modified on Oct 14, 2026

open delete

Examples

--domain is the WHOLE zone string from `bdy domain ls` (apex like "example.com" or multi-level like "my-app.example.dev"). --subdomain is OPTIONAL and only prepends a NEW sub-name to that zone. Never split a multi-level zone — it goes whole into --domain. route an apex zone you bought ("example.com") to an artifact
bdy distro route create distro-identifier --domain="example.com" --target "artifact=artifact-identifier:version"$

Route a multi-level zone you claimed ("my-app.example.dev") to an artifact — pass it WHOLE, do NOT split
bdy distro route create distro-identifier --domain="my-app.example.dev" --target "artifact=artifact-identifier:version"$

Route a NEW sub-name within a zone ("api.example.com") — subdomain is "api", zone is "example.com"
bdy distro route create distro-identifier --subdomain="api" --domain="example.com" --target "url=https://backend.internal"$

Route to a sandbox endpoint (no zone, distro's default domain is used)
bdy distro route create distro-identifier --subdomain="sandbox" --target "sandbox=sandbox-identifier:endpoint-name"$

Route to an artifact in two locations (default + Europe override)
bdy distro route create distro-identifier --subdomain="artifact" --target "artifact=artifact-identifier:version" --target "region=Europe,artifact=artifact-identifier:version2"$

Route only for js files under a sub-name
bdy distro route create distro-identifier --path="*.js" --subdomain="cdn" --target "artifact=artifact-identifier:version"$

Create redirect route
bdy distro route create distro-identifier --type="REDIRECT" --path="/my-url" --target "url=https://example.com/page"$

Return the result as JSON
bdy distro route create my-distro --type REDIRECT --target url=https://example.com --format json$