---
artifact_schema_version: 1
artifact_type: workflow
workflow_id: version-management-guide
---

# Day Shift Version Management Guide

Use this guide when you need to install, select, inspect, or remove local Day Shift CLI versions through the existing `day-shift` command.

Primary audience: human operators and agents managing local Day Shift runtime versions. Responsibility: explain how the implemented version manager behaves, which commands mutate local version-manager state, and which commands are read-only diagnostics. Route general workflow planning to `.day-shift/workflows/README.md`, command-boundary detail to `.day-shift/references/commands.md`, and release-build operations to the `release ...` command family.

## Command Placeholder

Resolve `<day-shift-cli>` to the command invocation that is valid for the current session. In installed/user mode, verify the packaged CLI with `day-shift --help` and use `day-shift`. In repository development mode, use `node dist/cli/index.js` when compiled `dist` output is current.

Installed user-facing examples should normally show `day-shift`.

## Version Manager Boundary

Version-manager operations are owned by:

```sh
day-shift version ...
```

Normal `day-shift ...` invocations remain the user-facing CLI path. The version manager keeps a stable `day-shift` shim and dispatches normal invocations to the selected installed version.

Version manager state lives under the platform Day Shift user-state root, inside `version-manager/`. Managed package files, aliases, receipts, logs, cache, config, and shims are version-manager state. Signed license files remain in the existing license directories and are not moved into managed package directories or project repositories.

## Installed Versions

Install from a local downloaded release archive or an unpacked package root:

```sh
day-shift version install --from ./release/0.1.10/download-bundle/day-shift-0.1.10-macos-linux-system-node.tar.gz --assert-version 0.1.10
```

The manager validates the source before writing managed state. It checks that the package is Day Shift, exposes the `day-shift` command, uses exact stable version metadata, satisfies runtime requirements, and matches `--assert-version` when provided.

List installed versions:

```sh
day-shift version list
```

`version list` reports local installed versions and offline, non-secret license summaries per installed version. It does not copy signed license payloads into version-manager state.

## Selection Order

When a normal `day-shift ...` invocation needs a managed version, the selector order is:

1. `DAY_SHIFT_VERSION`
2. nearest `.day-shift-version`, found by walking upward from the current directory
3. `.day-shift/local.toml`
4. `.day-shift/config.toml`
5. global `default` alias
6. single installed version fallback
7. visible error with diagnostics

Configured selectors that point at missing versions fail visibly. They do not silently fall through to another installed version.

Inspect the active selection and why it was selected:

```sh
day-shift version current
```

Use one version for one invocation:

```sh
DAY_SHIFT_VERSION=0.1.10 day-shift --version
```

## Defaults, Pins, And Aliases

Set the global default:

```sh
day-shift version use 0.1.10
```

Write a repository pin in the current workspace:

```sh
day-shift version pin 0.1.10
```

The repository pin writes `.day-shift-version`. It is shared repository state, so use it when the project should consistently run one Day Shift version.

List local aliases:

```sh
day-shift version alias list
```

Set a local alias:

```sh
day-shift version alias set stable 0.1.10
day-shift version alias set default stable
```

`default` is the global default selection alias. `stable` is explicit user-managed local state; install and network-check commands do not automatically move it.

Partial selectors such as `0`, `0.1`, and `latest-installed` resolve only against locally installed versions. Ambiguous selectors fail instead of guessing.

## Uninstall Safety

Uninstall always requires a target version:

```sh
day-shift version uninstall 0.1.10
```

The uninstall removes only the targeted managed package state and matching version-manager receipts. It does not remove signed license files, recovered purchase files, or authoritative license records.

If aliases or current-workspace repository selectors point at the target version, uninstall reports the affected selectors and blocks until you choose a safe outcome:

```sh
day-shift version uninstall 0.1.10 --replace-with 0.1.8
day-shift version uninstall 0.1.10 --confirm-selected-removal
```

Use `--replace-with` when you want selectors moved before removal. Use `--confirm-selected-removal` only when leaving those selectors unset or invalid is intentional.

## Diagnostics

Use `doctor` for local version-manager runtime context:

```sh
day-shift version doctor
```

Doctor output is read-only. It reports state-root paths, selected metadata, managed package path, shim mode, manager entrypoint, PATH candidates, PATH conflicts, package layout readiness, and offline state.

Use `current` when the main question is "which version would run and why":

```sh
day-shift version current
```

Use `list` when the main question is "what is installed and what is licensed":

```sh
day-shift version list
```

## Network Checks

Normal install, selection, uninstall, shim dispatch, and license verification are local/offline operations.

Availability checks require explicit approval:

```sh
day-shift version check --network
day-shift version check 0.1.10 --network
```

The check uses Day Shift-owned website metadata. It does not use GitHub, npm, or a public package registry. Declined, unavailable, or failed network checks do not mutate aliases or installed packages.

## Release Output And Website Downloads

The version manager installs from local release archives or unpacked package roots. A clean local release build can produce those archives under:

```txt
release/<version>/download-bundle/
```

Website static downloads live under:

```txt
apps/website/public/downloads/<version>/
```

When publishing a static website bundle from a clean local release, keep the two directories byte-for-byte aligned for the selected version. The release command family is local-only; website upload or CDN publication is outside the CLI release command contract.

Useful verification after syncing a versioned download bundle:

```sh
diff -qr release/0.1.10/download-bundle apps/website/public/downloads/0.1.10
node --test tests_v2/cli/version/release-handoff.test.js
pnpm --filter @day-shift/website validate
```

If the website validation build fails under a restricted sandbox with a Turbopack worker or port-bind error, rerun it in an environment that permits the build worker process. Treat typecheck, lint, and successful standalone build output as separate evidence when reporting the failure.

## Common Workflows

Install and select a new local version:

```sh
day-shift version install --from ./release/0.1.10/download-bundle/day-shift-0.1.10-macos-linux-system-node.tar.gz --assert-version 0.1.10
day-shift version use 0.1.10
day-shift version current
```

Pin a project to an installed version:

```sh
day-shift version pin 0.1.10
day-shift version current
```

Roll back globally to an older installed version:

```sh
day-shift version use 0.1.8
day-shift --version
```

Remove a version that is still selected:

```sh
day-shift version uninstall 0.1.10 --replace-with 0.1.8
day-shift version list
```

Check whether the website knows about a version without mutating local aliases:

```sh
day-shift version check 0.1.10 --network
day-shift version alias list
```

## Troubleshooting

- Missing selected version: run `day-shift version current` and inspect the selected source. Install the missing version, update the selector, or remove the stale pin/alias.
- Ambiguous partial selector: use an exact `major.minor.patch` version or adjust installed versions/aliases.
- Wrong package source: rerun install with a Day Shift release archive or unpacked package root that contains valid package metadata and `bin.day-shift`.
- PATH issue: run `day-shift version doctor` and inspect shim/path diagnostics.
- License mismatch: run `day-shift version list` to see offline release-line coverage per installed version, then install or recover the signed license file outside project repositories.
- WSL path issue: use a local path that maps safely into the WSL filesystem. Unsafe or unmappable Windows paths fail before package mutation.

## Command Help

Use local help as the exact command contract for the checkout you are running:

```sh
day-shift version --help
day-shift version install --help
day-shift version list --help
day-shift version use --help
day-shift version pin --help
day-shift version current --help
day-shift version uninstall --help
day-shift version doctor --help
day-shift version check --help
day-shift version alias --help
```
