Saved Run Aliases

Turn a long orchstep run invocation into a short, shareable name - typed or shorthand, overridable at call time, and validated by lint.

You keep typing the same long command:

orchstep run deploy --env production --var replicas=10 --vars-file overrides.yml

A saved alias names that invocation once so you can run it by name:

orchstep run prod_deploy

Aliases live in the aliases: block of orchstep.yml, so the shortcut travels with the repo instead of getting stuck in one person's shell. Unlike a shell alias, an OrchStep alias is an overridable default - any flag you pass at call time wins.

Define aliases

Add an aliases: block. Each entry is either a typed mapping (recommended) or a string shorthand.

# orchstep.yml
aliases:
  # Typed: every run option as a field. Introspectable and validated.
  prod_deploy:
    desc: Deploy to production (10 replicas)
    task: deploy
    env: production
    vars:
      replicas: 10
    vars_file: overrides.yml
    output: json

  # Shorthand: a raw command string. A leading `orchstep`/`run` is tolerated,
  # so you can paste from your shell history and barely edit it.
  staging_deploy: run deploy --env staging --var replicas=3

  # Typed, redirecting to a task in another workflow file.
  publish_release:
    desc: Publish from the release workflow
    file: release.yml
    task: publish

Fields (typed form)

Every field maps one-to-one to a run flag:

field	run flag
`desc`	-	description shown in `orchstep alias`
`task`	positional	task to run (required)
`file`	`-f` / `--file`	run from a different workflow file
`env`	`--env`	environment
`vars`	`--var key=value`	a map; merged with CLI `--var`
`vars_file`	`--vars-file`	variables file
`output`	`--output`	output format
`json_file`	`--json-file`	structured result file
`stdin_var`	`--stdin-var`	named stdin variable
`dry_run`	`--dry-run`	preview only

Run an alias

orchstep run prod_deploy

orchstep run <name> resolves a saved alias if one exists by that name, otherwise it runs a task by that name (unchanged behavior).

Override at call time

The alias is a starting point, not a cage. Flags you pass win over the alias, per value:

orchstep run prod_deploy --var replicas=20    # replicas is now 20
orchstep run prod_deploy --dry-run            # preview the resolved plan

prod_deploy still supplies production, overrides.yml, and JSON output - you only state the one thing that's different.

Inspect aliases

orchstep alias                # list every alias with its description
orchstep alias prod_deploy    # show the resolved `orchstep run ...` command

$ orchstep alias prod_deploy
prod_deploy
  Deploy to production (10 replicas)
  → orchstep run deploy --env production --var replicas=10 --vars-file overrides.yml --output json

Keep them honest with lint

Because an alias and a task share the orchstep run <name> namespace, an alias that shares a task's name would silently shadow it. orchstep lint catches it:

$ orchstep lint
⚠️  Found 1 warning(s) in orchstep.yml:

1. alias "deploy" has the same name as a task; `orchstep run deploy` would run the alias, not the task
   Location: aliases.deploy
   Suggestion: rename the alias (or the task) so names are unique

Lint also flags an alias that targets a missing task, or one that sets neither a task nor a shorthand command.

When to reach for an alias

A run you do often, with a fixed set of flags (prod_deploy, staging_deploy).
A run that targets another workflow file (file: + task:).
A long command you paste from history - capture it as a shorthand once.

For one-offs, just type the flags. For the twentieth time, name it.

See also: Variables & Outputs for the precedence model --var plugs into, and Previewing with Dry Run.

< Task Files Ad-hoc Commands >