Targets

district target adds and removes an app's targets, and chooses what each one serves. An app can have at most 5 durable targets and 20 unexpired preview targets. Exactly one live target is primary, and it is durable.

Each target has an environment, which selects the wrangler.jsonc bindings of its deployments. The primary target uses production and each preview target uses preview. Another durable target uses production or the name it was given. A target serves only deployments made for its environment. Bindings and environments describes the rules.

Every subcommand takes the repository from the clone in the current directory, or from a trailing positional argument, and accepts --workspace <id> and the environment flags. A repository with no app is a usage error that names district app create.

district target list

district target list [<repository>] [--workspace <id>] [--json] [--production | --staging | --dev]

Without --json, prints a header row, then one row per target: the label, host, kind, environment, expiry, custom domains that serve the host with their statuses, and the deployment that the target serves with its environment and its status. Every column is padded from the widest value, so a mixed list reads down one column. - stands for a value the row has not. The DOMAINS cell is empty for a target that holds no custom domain.

A target whose deployment was made in another environment than its own gets one line after the table: <label>: Environment change pending deployment. The target serves that deployment until a deployment in its own environment replaces it. With --json, each target has environment, and its currentDeployment has environment. A deployment made before environments existed has no environment: its DEPLOYMENT ENV cell is -, its environment is null, and it gets no line after the table.

Arguments

Argument	Description
`[<repository>]`	The repository, by `repo_` id or by slug. Without it, the clone in the current directory names one: its `origin` must be a District remote, which also names the environment.

Flags

Flag	Description	Default
`--workspace <id>`	The workspace of the repository, when the same slug names a repository in more than one workspace.	-
`--json`	Prints the targets as one JSON array.	`false`
`--production \| --staging \| --dev`	The environment to act in. Pass one at most. Without a flag, the command uses the environment that the last `district login` recorded, or production.	-

Output

$ district target list
LABEL      HOSTNAME                  KIND     ENV         EXPIRES               DOMAINS                    DEPLOYMENT  DEPLOYMENT ENV  STATUS
shopfront  shopfront.ondistrict.net  primary  production  -                     shop.example.com (active)  hdep_01K4…  production      succeeded
next       next.ondistrict.net       durable  staging     -                                                hdep_01K4…  production      succeeded
pr-42      pr-42.ondistrict.net      preview  preview     2026-09-04T09:00:00Z                             -           -               -
next: Environment change pending deployment

Exit codes

Exit code	Meaning
0	The rows were printed.
1	The API refused the call with its own message.
2	The command line names no repository, a slug that several workspaces hold, or a repository with no app.

district target create

district target create [<slug>] [<repository>] [--repository <ref>] [--preview | --env <name>] [--workspace <id>] [--production | --staging | --dev]

Adds a target. A label creates a durable target. --preview creates a preview target, whose label district-api generates and whose expiry the command prints. A command line must name a label or --preview, but not both. Otherwise, it is a usage error.

A durable target uses the production environment unless --env <name> names another. A preview target always uses preview. The environment selects the wrangler.jsonc section that the target's deployments bind. A durable target in another environment than production does not become the app's primary target.

--preview takes no label, so the first positional argument stays the label and --repository <ref> names the repository outside a clone. --repository with a second positional argument is a usage error.

Arguments

Argument	Description
`[<slug>]`	The label of the durable target to create. A label with `--preview` is a usage error, and so is a command line with neither.
`[<repository>]`	The repository, by `repo_` id or by slug. Without it, the clone in the current directory names one: its `origin` must be a District remote, which also names the environment.

Flags

Flag	Description	Default
`--repository <ref>`	The repository, by `repo_` id or by slug, for a command line whose first positional argument is the label. `--repository` with a second positional argument is a usage error.	-
`--preview`	Creates a preview target. district-api generates its label, and the command prints its expiry.	`false`
`--env <name>`	The environment of the durable target: a lower-case letter, then at most 31 lower-case letters, digits and hyphens. It is not the District environment that `--staging` selects. A preview target always uses `preview`.	`production`
`--workspace <id>`	The workspace of the repository, when the same slug names a repository in more than one workspace.	-
`--production \| --staging \| --dev`	The environment to act in. Pass one at most. Without a flag, the command uses the environment that the last `district login` recorded, or production.	-

Output

$ district target create --preview
created pr-42 (pr-42.ondistrict.net)
env preview
expires 2026-09-04T09:00:00Z
$ district target create next --env staging
created next (next.ondistrict.net)
env staging

The command prints the created target's label, host and environment. For a preview target, it also prints the expiry. A durable target in production on an app that has no primary target becomes the primary one, and the command prints primary for it.

Exit codes

Exit code	Meaning
0	The target exists. Its label and its host are printed.
1	The API refused the call with its own message: the app is at its cap for the kind, or the label is taken, reserved, or recently released.
2	The command line names neither a label nor `--preview`, names both, passes `--repository` with a second positional argument, passes an `--env` name that is not valid or another `--env` than `preview` with `--preview`, names no repository, names a slug that several workspaces hold, or names a repository with no app.

district target delete

district target delete <slug> [<repository>] [--yes] [--workspace <id>] [--production | --staging | --dev]

Deletes a target. The host answers 404 within about 15 seconds. The app's primary target cannot be deleted. Promote another target first with district target set-primary.

The API refuses a target that custom domains serve and names those domains. The command also prints Remove a domain with: district domain remove <hostname>. Remove each domain first. district domain add then attaches it to another target.

The command prints the resolved target and the environment, then asks Delete <hostname>? [y/N].

Arguments

Argument	Description
`<slug>`	The label of the target to delete.
`[<repository>]`	The repository, by `repo_` id or by slug. Without it, the clone in the current directory names one: its `origin` must be a District remote, which also names the environment.

Flags

Flag	Description	Default
`--yes`	Skips the "Delete <hostname>? [y/N]" question. A session with no terminal needs it.	`false`
`--workspace <id>`	The workspace of the repository, when the same slug names a repository in more than one workspace.	-
`--production \| --staging \| --dev`	The environment to act in. Pass one at most. Without a flag, the command uses the environment that the last `district login` recorded, or production.	-

Output

$ district target delete pr-42 --yes
deleted pr-42 (pr-42.ondistrict.net)

The label is unavailable to other workspaces for one hour after deletion. A delete and create cannot rename a target during that time. updateHostedAppTargetSlug renames it.

Exit codes

Exit code	Meaning
0	The target is deleted.
1	The confirmation was declined, or the API refused the call with its own message: the target is the primary one, or custom domains serve it.
2	The command line names no repository, a slug that several workspaces hold, a repository with no app, or no terminal can confirm.

district target set-primary

district target set-primary <slug> [<repository>] [--workspace <id>] [--production | --staging | --dev]

Makes a durable target the app's primary target, and prints it. The previous primary target stays live and serves what it served. A preview target is refused with the API's own message.

The primary target uses the production environment. A durable target in another environment is refused. The message names district target set-env, which moves the target to production, and the district deploy command that then deploys to it. For a target that serves nothing, that command is district deploy --target <slug>.

Arguments

Argument	Description
`<slug>`	The label of the durable target to make primary.
`[<repository>]`	The repository, by `repo_` id or by slug. Without it, the clone in the current directory names one: its `origin` must be a District remote, which also names the environment.

Flags

Flag	Description
`--workspace <id>`	The workspace of the repository, when the same slug names a repository in more than one workspace.
`--production \| --staging \| --dev`	The environment to act in. Pass one at most. Without a flag, the command uses the environment that the last `district login` recorded, or production.

Output

$ district target set-primary next
primary next (next.ondistrict.net)

A target in another environment than production:

$ district target set-primary next
next uses env staging, and the primary hostname must use production. Change it with: district target set-env next production, then deploy to it with: district deploy --from hdep_01K4… --target next

Exit codes

Exit code	Meaning
0	The target is the primary one.
1	The API refused the call: a preview target, with its own message, or a target in another environment, with the commands that move it to production.
2	The command line names no repository, a slug that several workspaces hold, or a repository with no app.

district target set-deployment

district target set-deployment <slug> <deploymentId> [<repository>] [--workspace <id>] [--production | --staging | --dev]

Points a target at a succeeded deployment of the same app and the same environment: a rollback, or a move between durable targets of one environment. The target keeps that deployment until the next repoint, and a deployment requested before this call cannot replace it when it finishes. A preview target's expiry moves 7 days ahead. A deployment made before environments existed has no environment and can serve a target of any environment.

Arguments

Argument	Description
`<slug>`	The label of the target to point.
`<deploymentId>`	The deployment to serve, by `hdep_` id. It must be a succeeded deployment of the same app, made for the target's environment.
`[<repository>]`	The repository, by `repo_` id or by slug. Without it, the clone in the current directory names one: its `origin` must be a District remote, which also names the environment.

Flags

Flag	Description
`--workspace <id>`	The workspace of the repository, when the same slug names a repository in more than one workspace.
`--production \| --staging \| --dev`	The environment to act in. Pass one at most. Without a flag, the command uses the environment that the last `district login` recorded, or production.

Output

$ district target set-deployment shopfront hdep_01K4…
shopfront serves hdep_01K4… (env production)
https://shopfront.ondistrict.net/

The line that names the target, the deployment it serves and the deployment's environment goes to stderr. The target's URL goes to stdout, as district deploy prints it, so $(district target set-deployment …) is the URL.

A value that is not a hdep_ id is a usage error before any call. A deployment that did not succeed, one whose script was removed, one that belongs to another app, and an expired preview target are refused with the API's own message.

A deployment made for another environment is refused: its bindings belong to that environment. A deployment of a preview target therefore cannot serve the primary target. The message names the target's environment and the district deploy --from command that deploys the same build to the target in the target's environment, with no new build:

$ district target set-deployment shopfront hdep_01K4…
deployment hdep_01K4… was made in another env than shopfront, which uses env production. Deploy its build to shopfront with: district deploy --from hdep_01K4… --target shopfront

Exit codes

Exit code	Meaning
0	The target serves the deployment. Its URL is printed.
1	The API refused the call: the deployment did not succeed, its script was removed, it belongs to another app or another environment, or the preview target is expired.
2	The command line names a value that is not a `hdep_` id, names no repository, names a slug that several workspaces hold, or names a repository with no app.

district target set-env

district target set-env <slug> <name> [<repository>] [--workspace <id>] [--production | --staging | --dev]

Changes the environment of a durable target that is not primary. The environment selects the wrangler.jsonc section that the target's next deployments bind, as Bindings and environments describes. The primary target always uses production, and a preview target always uses preview. The API refuses a change to either one.

The change applies to deployments created after it. The target keeps serving its current deployment until a deployment for the new environment finishes. A deployment created for the earlier environment that finishes after the change fails and does not serve the target.

Arguments

Argument	Description
`<slug>`	The label of the durable target.
`<name>`	The environment: a lower-case letter, then at most 31 lower-case letters, digits and hyphens, such as `staging`.
`[<repository>]`	The repository, by `repo_` id or by slug. Without it, the clone in the current directory names one: its `origin` must be a District remote, which also names the environment.

Flags

Flag	Description
`--workspace <id>`	The workspace of the repository, when the same slug names a repository in more than one workspace.
`--production \| --staging \| --dev`	The environment to act in. Pass one at most. Without a flag, the command uses the environment that the last `district login` recorded, or production.

Output

$ district target set-env next staging
next (next.ondistrict.net) uses env staging
Environment change pending deployment. Deploy to it with: district deploy --from hdep_01K4… --target next

The first line names the target, its host and its new environment. When the target serves a deployment made in another environment, a second line names the district deploy --from command that deploys the build of that deployment in the new environment.

Exit codes

Exit code	Meaning
0	The target uses the environment.
1	The API refused the call with its own message: the target is primary, or it is a preview target.
2	The command line names an environment name that is not valid, a label the app does not hold, no repository, a slug that several workspaces hold, or a repository with no app.