Initialize and manage a system

System presets provide selectable development-environment initialization steps for macOS, Ubuntu, and Windows, plus a small set of reversible managed system resources. They are not a general machine configuration or package-version manager. Use shine sys list from the installed version as the authoritative list of available items.

See built-in presets for each platform's profiles and for split-dns environment variables and safe preview steps.

Interactive lifecycle Plan confirmation can authorize the listed external code for that operation only, without saving trust. Automation and --yes require an existing grant. Shell live always requires Development trust; explicit --run-generators inspection also requires a grant.

Inspect before applying

shine sys list
shine sys list --all
shine sys info split-dns
shine sys bootstrap --dry-run

--dry-run shows selection results, provider/script invocations, and each persistent item-owned shell integration without changing the system. Some items require administrator access or additional environment variables; shine sys info <ITEM> lists those requirements.

For item IDs beginning with -, put options before --, then the item name, for example shine sys apply --dry-run -- -custom.

Select interactively or apply a profile

Choose one initialization method; review the Plan before using --yes:

Operation	Command
Choose items interactively	shine sys bootstrap
Initialize only mise	shine sys bootstrap mise
Initialize these items in order	shine sys bootstrap rust mise
Explicit items; approve non-interactively	shine sys bootstrap --item rust --item mise --yes
Use the recommended profile	shine sys bootstrap --preset recommended
Use the minimal profile	shine sys bootstrap --preset minimal
Preview with proxy settings	shine sys bootstrap --proxy --dry-run

• Positional item IDs bootstrap only those items, preserving their order and ignoring duplicates.
• Repeated --item is the explicit equivalent for scripts and setup orchestrators.
• Positional items, repeated --item, and --preset cannot be combined. Managed resources use sys apply, not sys bootstrap.
• In a non-interactive environment without an explicit profile, Shine uses the configured default.

After selection, a mutating run displays the planned changes and required permissions. Interactive approval defaults to No. Automation must pass --yes; this skips only the prompt, while the Plan is still shown and validated. --dry-run is an earlier preview and cannot be combined with --yes.

Review the Plan's administrator access, network access, and recovery limitations before approving. Use --verbose for detailed paths and steps. A permission declaration is not a safety guarantee: custom scripts and executable profile content run with your permissions and are not sandboxed. External code requires review and authorization.

During installation, Shine streams both standard output and standard error with the same item label, such as [rust]. Standard error can contain normal progress messages. Shine's own start and result messages use [shine]. The final result follows the installer's exit status and an installation check; a success message inside an installer log alone does not confirm success. Logs are not repeated after each item finishes. Output can still be delayed by the installer's own buffering.

A blank line separates the previous item’s result from the next installer’s start.

Installer colors and bold text are preserved on color-capable terminals. Set NO_COLOR=1 to disable them; redirected logs are plain text. Explicit CARGO_TERM_COLOR settings are respected. Labels stay aligned and independent of installer styles. Tabs in installer logs appear as four spaces to preserve readable indentation. On an interactive terminal, single-line progress updates refresh in place. Completed logs start on their own lines, including while an installer changes terminal modes or replaces a Cargo progress row. Long live rows are clipped to the current terminal width. Redirected output and TERM=dumb use ordinary log lines. Multi-line progress panels and full-screen installer interfaces are not emulated.

Shine enables Cargo's single-line progress on supported terminals, respecting explicit CARGO_TERM_PROGRESS_WHEN and CARGO_TERM_PROGRESS_WIDTH settings. Other installers may still suppress progress when their output is captured.

Optional command-version checks run non-interactively and wait at most 3 seconds. If a version check fails or times out, Shine still recognizes the executable as installed and uses its path instead of version details.

Installers may prompt for terminal input. Follow the current item's instructions and wait for it to finish before starting another operation.

On Ubuntu, the built-in Atuin installer runs non-interactively. Shine detects its default ~/.atuin/bin installation before the current shell has loaded the new PATH, then enables its shell integration. After opening a new shell, run atuin import auto to import existing history, and atuin register or atuin login if you want history synchronization. Bootstrap runs items sequentially, allows up to 30 minutes per installer, and stops at the first failed or timed-out item. Shine retains only a bounded tail for diagnostics while streaming output; log volume alone does not stop installation.

On Ubuntu, the built-in Yazi item installs prebuilt packages from the official stable APT repository, along with preview/runtime dependencies. It requires administrator access to add the repository key and source; Yazi installation itself does not require Rust or Cargo. Existing Yazi installations are detected and skipped rather than migrated between installers.

On Ubuntu, the built-in pnpm item uses the official standalone installer; Node.js, npm and Corepack are not prerequisites. It installs under ~/.local/share/pnpm; Shine manages its PATH integration. Open a new shell after bootstrap to use pnpm.

Ubuntu includes a minimal profile for production servers. It installs only Neovim, fzf, bat, eza, and zoxide, without shell-history synchronization, a prompt, the Node.js toolchain, or Homebrew. Always review the current steps with shine sys bootstrap --preset minimal --dry-run first.

Add --proxy when downloads require an HTTP proxy. Shine derives uppercase and lowercase proxy variables from PROXY_HOST, HTTP_PROXY_PORT, and PROXY_NO_PROXY in [env]; the default address is http://127.0.0.1:6152. Combine it with --dry-run to inspect the effective values.

Windows winget does not read these environment variables, so Shine also passes winget install --proxy. If that option is disabled, first run in an administrator PowerShell:

winget settings --enable ProxyCommandLineOptions

After initialization, inspect the recorded state:

shine sys status

This view shows the latest recorded result for each item, including bootstrap and managed system operations such as shine sys apply. Entries can come from different runs. It does not perform live checks of software versions or system configuration.

Upgrade bootstrap software with its owner

shine sys bootstrap is an ensure-present initializer, not a software update manager. Shine does not check or upgrade bootstrap software. Use the package manager or upstream tool that owns each item—such as Homebrew, apt, winget, mise, or rustup—to check for and install updates. Rerunning shine sys bootstrap only verifies that the selected software is present and does not upgrade it.

The built-in mise step follows the same boundary: it can install mise and add activation to managed shell profile content, but it does not create or update mise configuration and does not manage runtime versions. Use mise for mise.toml, tool installation, and version upgrades.

Manage shell integration state

Rust bootstrap makes the default Cargo binary directory (~/.cargo/bin) available in Ubuntu Bash/Zsh, macOS Zsh, and Windows PowerShell profiles. Open a new shell after bootstrap to use rustup, cargo, and rustc; bootstrap cannot change the calling shell's PATH.

If an older Ubuntu setup reports Rust as installed but the commands are missing, upgrade Shine, then run shine sys bootstrap rust and open a new shell. This repairs the shell integration without reinstalling an already detected Rust installation. For the current Bash/Zsh session, you can run . "$HOME/.cargo/env" if that file exists.

A successful bootstrap enables only the selected items' declared shell integrations. It does not disable integrations enabled by an earlier run, and a named selection profile is not a desired-state replacement for software or shell configuration.

Preview before disabling; re-enable only when needed:

Operation	Command
Preview disabling the integration	shine sys profile disable mise --dry-run
Disable the shell integration	shine sys profile disable mise
Re-enable the shell integration	shine sys profile enable mise

Declared PATH integrations add a directory only when it is absent; reloading the generated profile does not add duplicate entries, including paths containing spaces or shell pattern characters.

These commands modify only Shine-owned generated profile content. Disabling does not uninstall the software. Enabling first verifies the item's declared detection and asks you to bootstrap it when it is missing. A mutating run displays and freshly validates a snapshot-bound security Plan; automation must pass --yes, while --dry-run remains a separate preview. shine upgrade does not change or re-render profile enablement implicitly; use these explicit profile commands when that state should change.

Profile commands distinguish completed changes, an already enabled/disabled integration, and needs action. If profile merging needs manual attention, the current profile is preserved and the output points to the files to review. This warning alone does not cause a nonzero exit status; check the result before assuming the requested integration is active.

shine update and shine upgrade still manage only Shine configuration and managed system resources. They never upgrade this third-party software.

Top-level shine list includes managed system configuration recorded for the current operating system. Use shine sys status and shine sys info <ITEM> for details. update --verbose and upgrade --verbose also show skipped, current, and attention-required managed resources.

Managed system items

Some system configuration is managed declaratively and can be reapplied or safely removed:

Choose the operation you need; preview before applying or removing. Use --yes only after reviewing the same Plan, and run recovery only for an interrupted operation.

Operation	Command
Preview changes	shine sys apply --dry-run
Apply split-dns	shine sys apply split-dns
Non-interactive approval	shine sys apply split-dns --yes
Preview removal	shine sys uninstall split-dns --dry-run
Remove after review	shine sys uninstall split-dns
Review an interrupted managed operation	shine sys recover
Non-interactive approval	shine sys recover --yes

For managed system items, shine update compares the desired configuration with the installation record; shine upgrade also checks the actual system resource. On Windows, a split-DNS NRPT rule that matches both the recorded and desired configuration needs no update or administrator access. Use shine upgrade shell/<CATEGORY> to limit an upgrade to Shell presets.

Non-dry-run managed operations display a snapshot-bound Plan and default to No. --yes skips only the prompt, not Plan rendering, permission blockers, or fresh validation. Administrator access, if required, is requested separately after Plan approval.

If another Sys operation is running, wait for it to finish. If relevant state changes while waiting, review the new Plan before retrying.

If a managed operation is interrupted, later Sys changes stop and ask you to run shine sys recover. Recovery completes or rolls back only state that has not changed since the interruption. It never overwrites modified resources or unrelated shell-profile content.

Bootstrap scripts and package-manager operations are not undone by sys recover; follow the reported item and its package manager when they fail partway through.

For routing private domains across remote LANs to ZeroTier DNS, see the Chinese Biulight guide 使用 ZeroTier、CoreDNS 和 Shine 搭建异地私有域名网络.

On Ubuntu, split-dns expects applications to query the 127.0.0.53 systemd-resolved stub. Shine warns or refuses to write ineffective configuration when the stub is disabled. Re-enable DNSStubListener, or confirm that local resolution really passes through systemd-resolved, before applying the item.

System profiles merge with and preserve user content where possible. Use shine sys bootstrap --force-profile only when you explicitly want to back up and replace a conflicting profile.

Platform notes

• Managed shell profiles target zsh on macOS.
• Ubuntu supports bash and zsh.
• Windows system presets and profile integration use PowerShell.
• Ubuntu and macOS can detect the terminal background and set SHINE_TERMINAL_THEME; set SHINE_SYNC_TERMINAL_THEME=0 to disable it.

Retire an older local HTTP service

Version 2.4.0 removes HTTP serving and the SHINE_APP_HTTP_DIR script variable. Use local files for Surge and Clash Verge rules; application artifacts can keep persistent output in SHINE_STATE_DIR or SHINE_CACHE_DIR.

If you installed the old background service, remove it after upgrading to 2.4.0:

shine clear serve

Run this command as the user who installed the service. It stops the old service and removes its user service registration, even if the old configuration can no longer be loaded.

Before upgrading, the old binary's shine serve uninstall can also remove the service.

Upgrading does not remove existing files under the old runtime directory's http/. Keep any files you still need and update application references before deleting them.