Skip to content
waypost

Running from a checkout

A CLI you develop is also a CLI you use. The installed way therefore asks, before running its own code, which checkout should answer — over @sksizer/cli-tool/devlink, the same mechanism the other standalone CLIs in this family use.

The four layers

Section titled “The four layers”

First hit wins.

| Layer | Wins when | Off when | | ----- | ---------------------------------------------------- | ------------------------------- | | env | WAY_HOME names a waypost checkout | never — explicit always applies | | cwd | the current directory is inside a waypost checkout | WAY_CWD_DEV=0 | | link | way dev link has pointed the machine at a checkout | — | | local | none of the above: the install itself | — |

A checkout is any directory carrying bin/way.js — a git clone, a worktree, or the copy an npm install unpacked. A layer naming a directory that is no longer a checkout is skipped rather than fatal, so deleting a linked checkout does not break the install. The shim prints which entry it chose on stderr; WAY_QUIET=1 silences that.

The verbs

Section titled “The verbs”
Terminal window
way dev install          # once: symlink this checkout's bin/way.js onto PATH as way + waypost
way dev link             # this checkout answers everywhere (default: the one above the cwd)
way dev link ~/src/other # or a named one
way dev history          # every checkout ever linked, most recent first
way dev use #2           # switch to the second entry …
way dev use canonical    # … or back to the install
way dev status           # which checkout runs now, and why
way dev off              # same as use canonical

Every verb takes --json and --dry-run. history shows each checkout’s branch and HEAD as they were when it was linked, marks the active one with *, and marks a deleted one missing.

Where the state lives

Section titled “Where the state lives”

Under the per-OS config home: ~/Library/Application Support/way on macOS, ${XDG_CONFIG_HOME:-~/.config}/way elsewhere. home holds the active link as one absolute path; history.jsonl is the append-only record history and use #n read. Both are safe to delete — losing them costs the link, not the install.