Files
skillshare/website/docs/reference/appendix/environment-variables.md
T
Willie 2c3003e04f feat(website): complete website revamp — Diátaxis IA, blog, recipes, quickstarts
Restructure the entire documentation site following the Diátaxis framework
(Learn / How-to / Understand / Reference) with new content across 110 files.

## Information Architecture (M1)
- Move all docs to Diátaxis directory structure (learn/, how-to/, understand/, reference/)
- Add client-redirects plugin for old URL compatibility
- Rewrite sidebar, navbar, and footer to match new IA
- Update all internal cross-references

## Homepage + Quickstarts (M2)
- Add scenario entry cards to homepage with hand-drawn design
- 5 quickstart pages: Claude Code, GitHub Copilot (with copy mode recommendation),
  Codex, Multiple Tools, Dev Containers, Playground

## Blog + Changelog (M3)
- Enable Docusaurus blog plugin with authors.yml
- 5 blog posts: 5-min tutorial, managing 50+ skills, skillshare vs vercel/skills
  comparison, team sharing patterns, write your first skill
- Static /changelog page from CHANGELOG.md

## Recipes + Philosophy (M4)
- 5 recipe pages: CI/CD validation, enterprise skills, project setup,
  cross-machine sync, team onboarding
- 3 philosophy pages: why-local-first, security-first, sync-modes-explained

## Content Polish
- Cross-validate all content against CLI source (19 inaccuracies fixed)
- Lowercase "skillshare" throughout (avoid brand conflict with Skillshare Inc.)
- Add registry.yaml to file structure and Key Paths docs
- Highlight multi-platform git support (GitHub, GitLab, Bitbucket, Gitea,
  Azure DevOps, AtomGit, Codeberg)
- Standardize brew install command
- Add AsciinemaPlayer component (cast recordings pending)
2026-02-26 04:52:29 +08:00

281 lines
7.4 KiB
Markdown

---
sidebar_position: 2
---
# Environment Variables
All environment variables recognized by skillshare.
## Configuration
### SKILLSHARE_CONFIG
Override the config file path.
```bash
SKILLSHARE_CONFIG=~/custom-config.yaml skillshare status
```
**Default:** `~/.config/skillshare/config.yaml`
---
### XDG_CONFIG_HOME
Override the base configuration directory per the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/latest/).
```bash
export XDG_CONFIG_HOME=~/my-config
# skillshare will use ~/my-config/skillshare/
```
**Default behavior:**
| Platform | Default |
|----------|---------|
| Linux | `~/.config/skillshare/` |
| macOS | `~/.config/skillshare/` |
| Windows | `%AppData%\skillshare\` |
**Priority:** `SKILLSHARE_CONFIG` > `XDG_CONFIG_HOME` > platform default.
:::note
If you set `XDG_CONFIG_HOME` after initial setup, move your existing `~/.config/skillshare/` directory to the new location manually.
:::
---
### XDG_DATA_HOME
Override the data directory (backups, trash).
```bash
export XDG_DATA_HOME=~/my-data
# skillshare will use ~/my-data/skillshare/backups/ and ~/my-data/skillshare/trash/
```
**Default:** `~/.local/share/skillshare/`
---
### XDG_STATE_HOME
Override the state directory (operation logs).
```bash
export XDG_STATE_HOME=~/my-state
# skillshare will use ~/my-state/skillshare/logs/
```
**Default:** `~/.local/state/skillshare/`
---
### XDG_CACHE_HOME
Override the cache directory (version check cache, UI dist cache).
```bash
export XDG_CACHE_HOME=~/my-cache
# skillshare will use ~/my-cache/skillshare/
```
**Default:** `~/.cache/skillshare/`
:::tip Automatic migration
Starting from v0.13.0, skillshare follows the XDG Base Directory Specification for backups, trash, and logs. If you're upgrading from an older version, these directories are automatically migrated from `~/.config/skillshare/` to their proper XDG locations on first run.
:::
---
## GitHub API
### GITHUB_TOKEN
GitHub personal access token.
**Used for:**
- GitHub API requests (`skillshare search`, `skillshare upgrade`)
- **Git clone authentication** — automatically injected when installing private repos via HTTPS
**Creating a token:**
1. Go to https://github.com/settings/tokens
2. Generate new token (classic)
3. Scope: `repo` for private repos, none for public repos
4. Copy the token
Official docs: [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
**Usage:**
```bash
export GITHUB_TOKEN=ghp_your_token_here
skillshare install https://github.com/org/private-skills.git --track
```
**Windows:**
```powershell
# Current session
$env:GITHUB_TOKEN = "ghp_your_token"
# Permanent
[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_your_token", "User")
```
---
## Git Authentication
These variables enable HTTPS authentication for private repositories. When set, skillshare automatically injects the token during `install` and `update` — no URL modification needed.
See [Private Repositories](/docs/reference/commands/install#private-repositories) for details and CI/CD examples.
### GITLAB_TOKEN
GitLab personal access or CI job token. Used for HTTPS clone of GitLab-hosted private repos.
**Creating a token:**
1. Go to https://gitlab.com/-/user_settings/personal_access_tokens
2. Add new token
3. Scopes: `read_repository` (pull only) or `read_repository` + `write_repository` (push & pull)
4. Copy the token (prefix `glpat-`)
Official docs: [Token overview](https://docs.gitlab.com/security/tokens/)
:::warning Token types
Only **Personal Access Token** (`glpat-`) and **Project/Group Access Token** work for git operations. Feed Tokens (`glft-`) do **not** have git access.
:::
```bash
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
skillshare install https://gitlab.com/org/skills.git --track
```
**Windows:**
```powershell
$env:GITLAB_TOKEN = "glpat-xxxxxxxxxxxxxxxxxxxx"
```
### BITBUCKET_TOKEN
Bitbucket repository access token, or app password. Used for HTTPS clone of Bitbucket-hosted private repos.
**Creating a token (repository access token):**
1. Go to Repository → Settings → Access tokens
2. Create token with **Read** permission (pull only) or **Read + Write** (push & pull)
3. Copy the token — uses `x-token-auth` automatically (no username needed)
**Creating a token (app password):**
1. Go to https://bitbucket.org/account/settings/app-passwords/
2. Create app password with **Repositories: Read** (pull only) or **Repositories: Read + Write** (push & pull)
3. Also set `BITBUCKET_USERNAME` (or include it in the URL as `https://<username>@bitbucket.org/...`)
Official docs: [Access tokens](https://support.atlassian.com/bitbucket-cloud/docs/access-tokens/)
```bash
export BITBUCKET_USERNAME=your_bitbucket_username
export BITBUCKET_TOKEN=your_app_password
skillshare install https://bitbucket.org/team/skills.git --track
```
**Windows:**
```powershell
$env:BITBUCKET_USERNAME = "your_bitbucket_username"
$env:BITBUCKET_TOKEN = "your_app_password"
```
### BITBUCKET_USERNAME
Bitbucket username used with `BITBUCKET_TOKEN` when that token is an app password.
```bash
export BITBUCKET_USERNAME=your_bitbucket_username
export BITBUCKET_TOKEN=your_app_password
skillshare install https://bitbucket.org/team/skills.git --track
```
### SKILLSHARE_GIT_TOKEN
Generic fallback token for any HTTPS git host. Used when no platform-specific token is set.
```bash
export SKILLSHARE_GIT_TOKEN=your_token
skillshare install https://git.example.com/org/skills.git --track
```
**Windows:**
```powershell
$env:SKILLSHARE_GIT_TOKEN = "your_token"
```
**Token priority:** Platform-specific (`GITHUB_TOKEN`, `GITLAB_TOKEN`, `BITBUCKET_TOKEN`) > `SKILLSHARE_GIT_TOKEN`.
---
## Testing
### SKILLSHARE_TEST_BINARY
Override the CLI binary path for integration tests.
```bash
SKILLSHARE_TEST_BINARY=/path/to/skillshare go test ./tests/integration
```
**Default:** `bin/skillshare` in project root
---
## Usage Examples
### Temporary override
```bash
# Single command
SKILLSHARE_CONFIG=/tmp/test-config.yaml skillshare status
# Multiple commands
export SKILLSHARE_CONFIG=/tmp/test-config.yaml
skillshare status
skillshare list
unset SKILLSHARE_CONFIG
```
### Permanent setup (macOS/Linux)
Add to `~/.bashrc` or `~/.zshrc`:
```bash
export GITHUB_TOKEN="ghp_your_token_here"
```
### Permanent setup (Windows)
```powershell
[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_your_token", "User")
```
---
## Summary
| Variable | Purpose | Default |
|----------|---------|---------|
| `SKILLSHARE_CONFIG` | Config file path | `~/.config/skillshare/config.yaml` |
| `XDG_CONFIG_HOME` | Base config directory | `~/.config` (Linux/macOS), `%AppData%` (Windows) |
| `XDG_DATA_HOME` | Data directory (backups, trash) | `~/.local/share` |
| `XDG_STATE_HOME` | State directory (logs) | `~/.local/state` |
| `XDG_CACHE_HOME` | Cache directory (version check, UI) | `~/.cache` |
| `GITHUB_TOKEN` | GitHub API + git clone auth | None |
| `GITLAB_TOKEN` | GitLab git clone auth | None |
| `BITBUCKET_TOKEN` | Bitbucket git clone auth | None |
| `BITBUCKET_USERNAME` | Bitbucket username for app password auth | None |
| `SKILLSHARE_GIT_TOKEN` | Generic git clone auth (fallback) | None |
| `SKILLSHARE_TEST_BINARY` | Test binary path | `bin/skillshare` |
---
## Related
- [Configuration](/docs/reference/targets/configuration) — Config file reference
- [Windows Issues](/docs/troubleshooting/windows) — Windows environment setup