Files
skillshare/website/docs/reference/commands/upgrade.md
T
Charitarth ChughandClaude Opus 5.5 64c8a3f34e feat: add Nix flake and handle Nix-store installs in upgrade (#764)
* feat: add Nix flake and stop self-upgrade of Nix-store installs

Add flake.nix with packages, overlays.default, checks and a formatter,
building nix/package.nix with the unit tests in the Nix sandbox. The
version comes from the Release Please manifest, so releases need no Nix
edit. A Nix workflow runs `nix flake check` on non-docs changes.

`skillshare upgrade` now detects binaries under /nix/store/ and prints
`nix profile upgrade skillshare` instead of replacing a read-only store
path; update notices and doctor suggest the same command.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(upgrade): give Nix installs the right update path everywhere

The first flake commit sent every /nix/store binary to `nix profile
upgrade`, failed a plain `skillshare upgrade` with exit 1 even when the
CLI was current, and left the dashboard with a generic 500.

- Tell `nix profile` installs (the profile manifest lists the store path)
  from NixOS, Home Manager and overlay installs, which are told to update
  their configuration and rebuild. Detection lives in one helper shared by
  the update notice, doctor, upgrade and the dashboard.
- `upgrade` on Nix reports "already up to date" or prints the hint and
  exits 0; the built-in skill still updates.
- The dashboard runs the upgrade so the skill updates, then answers
  409 `upgrade.nix` with the command when a newer CLI waits on Nix. The
  UI shows localized text for it in all 11 locales.
- Installs skip the unit tests; the flake's checks enable them. postPatch
  lowers only the go directive's patch version and fails evaluation with
  a clear message when go.mod needs a newer Go minor. CI also builds the
  package on macOS.
- Docs, translations, the built-in skill reference and the release topic
  describe the new behaviour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 15:53:57 +08:00

152 lines
4.9 KiB
Markdown

---
sidebar_position: 3
---
# upgrade
Upgrade the skillshare CLI binary and/or the built-in skillshare skill.
```bash
skillshare upgrade # Upgrade both CLI and skill
skillshare upgrade --cli # CLI only
skillshare upgrade --skill # Skill only
```
## When to Use
- A new version of the skillshare CLI is available
- The built-in skillshare skill needs updating
- After `doctor` reports an available update
```text
skillshare upgrade --skill --dry-run
Skill v0.21.12 → v0.21.13 · would download
Dry run — nothing was written
```
## What Happens
```mermaid
flowchart TD
TITLE["skillshare upgrade"]
CLI["1. Upgrade CLI binary"]
SKILL["2. Upgrade built-in skill"]
TITLE --> CLI --> SKILL
```
## Options
| Flag | Description |
|------|-------------|
| `--cli` | Upgrade CLI only |
| `--skill` | Upgrade skill only (prompts if not installed) |
| `--force, -f` | Skip confirmation prompts |
| `--dry-run, -n` | Preview without making changes |
| `--help, -h` | Show help |
## Homebrew Users
If you installed via Homebrew, `skillshare upgrade` automatically delegates to `brew upgrade`:
```bash
skillshare upgrade
# → brew update && brew upgrade skillshare
```
You can also use Homebrew directly:
```bash
brew upgrade skillshare
```
## Nix Users {#nix-users}
If you installed with Nix, `skillshare upgrade` leaves the CLI alone, because replacing a file in the Nix store would corrupt it. When a newer version exists, it tells you how to get it instead. For `nix profile add`, that is:
```bash
nix profile upgrade skillshare
```
When a NixOS, Home Manager or overlay configuration provides skillshare, update skillshare in that configuration (for a flake input, `nix flake update skillshare`) and rebuild. The dashboard's upgrade button shows the same advice.
`skillshare upgrade --skill` still updates the built-in skill.
## Examples
```bash
# Standard upgrade (both CLI and skill)
skillshare upgrade
# Preview what would be upgraded
skillshare upgrade --dry-run
# Force upgrade without prompts
skillshare upgrade --force
# Upgrade only the CLI binary
skillshare upgrade --cli
# Upgrade only the skillshare skill
skillshare upgrade --skill
```
## After Upgrading
If you upgraded the skill, run `skillshare sync` to distribute it:
```bash
skillshare upgrade --skill
skillshare sync # Distribute to all targets
```
## What Gets Upgraded
### CLI Binary
The `skillshare` executable itself. Downloads from GitHub releases.
The archive is verified against the release's `checksums.txt` before your running binary is
replaced, so a damaged or mismatched download stops the upgrade instead of installing itself.
The current binary stays untouched, and the error names the mismatch.
In a terminal, the download shows how much has arrived, so a slow connection does not
look like a hang. The Web UI assets below show the same.
```
Downloading v0.21.4... 3.2 MB / 9.1 MB
```
The install script now defaults to `~/.local/bin`, where normal updates do not need `sudo`. Existing installations keep their current location.
If the binary is in a protected directory (e.g., `/usr/local/bin`), skillshare asks `sudo` to replace only the binary — no manual prefix needed. The built-in skill, UI assets, and logs are still written as you, so don't run the whole upgrade with `sudo`: that leaves root-owned files in your skills source, and a later `git pull` fails with `Permission denied`.
If an earlier upgrade already left such files, updating the built-in skill fails with `permission denied`, and the error shows the command that gives the skills source back to you, for example:
```bash
sudo chown -R "$(id -un)" ~/.config/skillshare/skills
```
When there is no terminal to ask for a password on (the dashboard's **Update now** button, CI), the upgrade stops right away and tells you to run `skillshare upgrade` in a terminal instead of waiting for input. Cached `sudo` credentials and `NOPASSWD` setups still upgrade without a prompt.
### Web UI Assets
After upgrading, skillshare pre-downloads the Web UI frontend assets for the new version. These are cached at `~/.cache/skillshare/ui/<version>/` and served when you run `skillshare ui`.
The pre-download keeps both the new version's assets and the pre-upgrade CLI version's assets, so an already-running UI server can still load its files. Other cached versions are removed. Restart the app or UI server between upgrades: a second upgrade without a restart can remove the oldest server's assets.
If the pre-download fails (e.g. network issues), the assets will be downloaded on the next `skillshare ui` launch instead.
### skillshare Skill
The built-in `skillshare` skill that adds the `/skillshare` command to AI CLIs. Located at:
```
~/.config/skillshare/skills/skillshare/SKILL.md
```
## See Also
- [update](/docs/reference/commands/update) — Update other skills and repos
- [status](/docs/reference/commands/status) — Check current versions
- [doctor](/docs/reference/commands/doctor) — Diagnose issues