Copyable Commands

This page keeps common workstation operations in small, copyable command blocks. Commands are grouped by safety level so a fresh-machine setup can stay visible and recoverable.

Command Rules

• Prefer one phase per command block.
• Run checks and dry-runs before commands that write to the machine.
• Keep interactive commands available, but also document a non-interactive equivalent.
• Print or document the next step when a command cannot safely continue.
• Keep package-manager manifests as the source of truth instead of hiding installs in ad hoc scripts.

Fresh Machine

Install Homebrew first if the machine does not have it yet:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Load Homebrew into the current shell:

eval "$(/opt/homebrew/bin/brew shellenv)"

Install ghq and configure the canonical project root:

brew install ghq
git config --global ghq.root ~/repos

Check the configured ghq project root:

git config --global --get ghq.root

Clone this repository into the ghq layout:

ghq get git@github.com:YunYouJun/workstation.git
cd "$(ghq list -p github.com/YunYouJun/workstation)"

If ghq is not available yet, clone directly into the same path:

mkdir -p ~/repos/github.com/YunYouJun
git clone git@github.com:YunYouJun/workstation.git ~/repos/github.com/YunYouJun/workstation
cd ~/repos/github.com/YunYouJun/workstation

Install packages declared by this repository:

brew bundle --file Brewfile

Install the default Node.js runtime:

fnm install --lts
fnm default lts-latest

Install optional desktop apps:

pnpm software:install --apps

Install workspace dependencies and build the CLI:

pnpm install
pnpm build

Safe Checks

Inspect the current dotfiles state:

workstation dotfiles doctor
workstation dotfiles status
workstation dotfiles diff

List available init tasks:

wst init --list

Preview Git includeIf identity routing setup:

wst init git.include-if --git-profile 'id=github;host=github.com;name=Your Name;email=you@example.com'

Preview a restore from the repository into $HOME:

workstation dotfiles pull --dry-run

Preview a push from $HOME into the repository:

workstation dotfiles push --dry-run

Preview cloning the recently active YunYouJun repositories:

workstation projects clone-active

Preview cloning the 20 most recently active YunYouJun repositories:

workstation projects clone-active --limit 20

Preview the same flow with short aliases:

wst p active --limit 20

Select repositories interactively:

wst p active --limit 50 -i

Preview cloning from a local project manifest:

wst p manifest --file projects.local.yaml

Preview reading a project manifest from a private configuration repository:

wst p manifest https://git.example.com/<user>/<config-repo> --group common

Configure the default count through the script entry:

WORKSTATION_ACTIVE_PROJECT_LIMIT=20 pnpm projects:clone-active

Check local projects for uncommitted, unpushed, or stashed work:

workstation projects status
wst p status --check
wst p status --max-depth 8
pnpm projects:status

Check whether Homebrew packages are already installed:

brew bundle check --file Brewfile

Check whether optional desktop apps are already installed:

pnpm software:check --apps

Show which catalog apps are missing:

pnpm software:missing

Open official download pages for selected apps:

pnpm software:open microsoft-todo vscode neteasemusic qq wechat codex chrome raycast feishu

Apply Changes

Restore managed dotfiles into $HOME after reviewing the dry-run:

workstation dotfiles pull --force

Save local dotfile changes back into the repository after reviewing the dry-run:

workstation dotfiles push --force

Apply chezmoi-managed files directly:

workstation dotfiles chezmoi apply

Apply Git includeIf identity routing after reviewing the dry-run:

wst init git.include-if --git-profile 'id=github;host=github.com;name=Your Name;email=you@example.com' --yes

Clone the recently active YunYouJun repositories after reviewing the dry-run:

workstation projects clone-active --yes

Restart the current shell:

exec zsh

Interactive Flow

Use the interactive sync flow when choosing direction and files by hand:

workstation dotfiles sync -i

Use interactive init when choosing setup tasks and entering machine-local identity values by hand:

wst init -i

Equivalent non-interactive restore flow:

workstation dotfiles sync --direction pull --dry-run
workstation dotfiles sync --direction pull --force

Equivalent non-interactive save flow:

workstation dotfiles sync --direction push --dry-run
workstation dotfiles sync --direction push --force

Release CLI

Before the first GitHub Actions publish, configure npm Trusted Publishing for @yunyoujun/workstation in the package settings:

Publisher: GitHub Actions
Repository: YunYouJun/workstation
Workflow filename: release.yml
Allowed action: npm publish

Publish a new version:

pnpm release
git push --follow-tags

After a v* tag is pushed, GitHub Actions validates and publishes packages/cli.

Future Commands

As the repository grows beyond dotfiles, prefer a broader workstation command with domain subcommands while keeping dotfiles as a compatibility alias for the existing sync workflow.

workstation doctor
workstation bootstrap --dry-run
workstation packages install --dry-run
workstation dotfiles pull --dry-run
workstation projects clone-active