# `mix castle.relup`
[🔗](https://github.com/ausimian/forecastle/blob/1.0.0/lib/mix/tasks/castle.relup.ex#L1)

Generates a relup for an existing target release.

    mix castle.relup --target <path> --fromto <spec>

For a release being assembled now, prefer `upgrade_from:` with
`Castle.customize/1`; Forecastle then writes the relup immediately before
`:tar`. Use this task for an existing target, separate upgrade and downgrade
baselines, explicit strategies, or a dry run.

## Options

- `--target` names the target `.rel` path without the extension.
- `--fromto` generates both directions from a baseline.
- `--upfrom` generates only an upgrade from a baseline.
- `--downto` generates only a downgrade to a baseline.
- `--outdir` selects an existing output directory. It defaults to the current
  directory.
- `--hot` requires every transition to remain hot.
- `--restart` makes every transition restart the emulator.
- `--dry-run` validates and reports the plan without writing the relup.

Supply at least one baseline switch. `--hot` and `--restart` are mutually
exclusive.

## Baselines

Baseline switches accept three sources:

    rel:_build/prod/rel/my_app/releases/1.0.0/my_app
    tar:artifacts/my_app-1.0.0.tar.gz
    ref:v1.0.0

A path without a prefix means `rel:`. `rel:` names an assembled release,
`tar:` unpacks a release artifact, and `ref:` builds a git revision. Prefer
`tar:` when the shipped artifact is available because a rebuilt baseline may
differ from the deployed code.

`--target` is always a path, not a baseline spec.

The task writes a complete relup through a staging file. A failed generation
leaves any existing output untouched. Use the default output directory when a
later release build should package the project-root `relup`.

## Strategies

`auto`, the default, keeps a transition hot unless the ERTS changes or an
unowned application changes version without a matching appup. Upgrade and
downgrade directions are classified separately. A missing appup for an owned
application remains an error. Added and removed applications remain hot.

`--hot` rejects a missing appup, ERTS change, or appup instruction that would
restart the emulator. Use it for pipelines that require hot deployment.

`--restart` emits a single `restart_emulator` instruction for each transition.
It does not read appups or call `:systools`.

Forecastle reports every restart edge and its reason. It supports only the
one-stage `restart_emulator` transition and rejects `restart_new_emulator`,
including instructions introduced by appups.

## Dry runs

`--dry-run` resolves baselines and generates the complete plan without
publishing the relup. Its exit status reports whether generation succeeded.
It cannot detect a destination write failure.

Baseline resolution may still write to `_build/castle/baselines`: `tar:`
unpacks an artifact and `ref:` builds a revision. The relup and output
directory remain untouched.

---

*Consult [api-reference.md](api-reference.md) for complete listing*