mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-18 18:04:17 +00:00
Bind provider credentials to canonical or explicitly configured HTTPS origins and preserve that policy across remote consumers. Reject cross-site credentialed reads, linked fallback directories, and discovered-agent writes outside the source; audit staged content before rooted atomic publication. Add boundary regressions, private Git update coverage, stable cross-platform fixtures, and aligned documentation. Verified the integrated main baseline with all executed CI checks passing.
531 lines
17 KiB
Markdown
531 lines
17 KiB
Markdown
---
|
|
sidebar_position: 2
|
|
---
|
|
|
|
# Environment Variables
|
|
|
|
All environment variables recognized by skillshare.
|
|
|
|
## Configuration
|
|
|
|
### SKILLSHARE_AUTO_UPDATE_CHECK {#skillshare_auto_update_check}
|
|
|
|
Override global `updates.auto_check` for automatic release-version checks and notifications.
|
|
|
|
```bash
|
|
SKILLSHARE_AUTO_UPDATE_CHECK=false skillshare status
|
|
```
|
|
|
|
**Default:** `updates.auto_check` in config.yaml, or `true` when unset.
|
|
Accepts `true`/`false`, `1`/`0`, `t`/`f` and Go boolean case variants; empty or
|
|
invalid values are ignored. The environment takes precedence without rewriting config.
|
|
CLI, web UI and compatible desktop app version notifications are suppressed when false;
|
|
explicit checks and upgrades remain available. GUI apps must inherit this variable
|
|
when launched. Desktop support requires an app release that includes
|
|
[skillshare-app#126](https://github.com/runkids/skillshare-app/pull/126); upgrading
|
|
the CLI alone does not disable checks in older desktop builds. See [updates](/docs/reference/commands/updates).
|
|
|
|
### 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, machine-local project registrations and their mutation locks).
|
|
|
|
```bash
|
|
export XDG_STATE_HOME=~/my-state
|
|
# skillshare will use ~/my-state/skillshare/logs/, ~/my-state/skillshare/projects/
|
|
```
|
|
|
|
**Default:** `~/.local/state/skillshare/`
|
|
|
|
When unset, project registrations and their locks default to `%LOCALAPPDATA%\skillshare\state` on Windows. Keep this override local to the machine. See [shared and local registrations](../commands/project.md#local-registrations).
|
|
|
|
---
|
|
|
|
### 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.
|
|
:::
|
|
|
|
---
|
|
|
|
### SKILLSHARE_GITLAB_HOSTS
|
|
|
|
Comma-separated list of self-managed GitLab hostnames to treat with nested subgroup support. Useful in CI/CD where you may not have a config file.
|
|
|
|
```bash
|
|
SKILLSHARE_GITLAB_HOSTS=git.company.com,code.internal.io skillshare install git.company.com/team/frontend/ui
|
|
```
|
|
|
|
When both the env var and config file [`gitlab_hosts`](/docs/reference/targets/configuration#gitlab_hosts) are set, their values are **merged** (deduplicated). Invalid entries (containing scheme, path, port, or empty) are silently skipped.
|
|
|
|
**Default:** None (only config file values are used)
|
|
|
|
---
|
|
|
|
### SKILLSHARE_AZURE_HOSTS
|
|
|
|
Comma-separated list of self-hosted Azure DevOps Server hostnames.
|
|
|
|
```bash
|
|
SKILLSHARE_AZURE_HOSTS=azuredevops.mycompany.com,tfs.internal.io
|
|
```
|
|
|
|
When both the env var and config file [`azure_hosts`](/docs/reference/targets/configuration#azure_hosts) are set, their values are **merged** (deduplicated). Invalid entries in the env var are silently skipped.
|
|
|
|
**Default:** _(none)_
|
|
|
|
### SKILLSHARE_GITEA_HOSTS
|
|
|
|
Comma-separated list of self-hosted Gitea hostnames. Hosts containing `gitea` in the name are detected without it.
|
|
|
|
```bash
|
|
SKILLSHARE_GITEA_HOSTS=git.company.com,code.internal.io
|
|
```
|
|
|
|
Merged with the config file's [`gitea_hosts`](/docs/reference/targets/configuration#gitea_hosts).
|
|
|
|
**Default:** _(none)_
|
|
|
|
### SKILLSHARE_CNB_HOSTS
|
|
|
|
Comma-separated list of self-hosted CNB hostnames. `cnb.cool` is detected without it.
|
|
|
|
```bash
|
|
SKILLSHARE_CNB_HOSTS=cnb.company.com
|
|
```
|
|
|
|
Merged with the config file's [`cnb_hosts`](/docs/reference/targets/configuration#cnb_hosts).
|
|
|
|
**Default:** _(none)_
|
|
|
|
---
|
|
|
|
## Web UI
|
|
|
|
### SKILLSHARE_UI_BASE_PATH
|
|
|
|
Set the URL sub-path for serving the web dashboard behind a reverse proxy.
|
|
|
|
```bash
|
|
SKILLSHARE_UI_BASE_PATH=/skillshare skillshare ui --host 0.0.0.0 --no-open
|
|
```
|
|
|
|
Equivalent to `--base-path /skillshare`. The flag takes precedence if both are set.
|
|
|
|
**Default:** None (dashboard served at root `/`)
|
|
|
|
See [Reverse Proxy](/docs/reference/commands/ui#reverse-proxy) for Nginx and Caddy examples.
|
|
|
|
### SKILLSHARE_UI_TRUSTED_ORIGINS
|
|
|
|
Comma-separated addresses the web dashboard answers at besides `localhost` and IP addresses, such as the domain of a reverse proxy.
|
|
|
|
```bash
|
|
SKILLSHARE_UI_TRUSTED_ORIGINS=https://tools.example.com skillshare ui --host 0.0.0.0 --no-open
|
|
```
|
|
|
|
Equivalent to `--trusted-origin https://tools.example.com`. When the flag is given, the variable is ignored.
|
|
|
|
**Default:** None
|
|
|
|
See [Reverse Proxy](/docs/reference/commands/ui#reverse-proxy).
|
|
|
|
---
|
|
|
|
## GitHub API
|
|
|
|
### GITHUB_TOKEN
|
|
|
|
GitHub personal access token.
|
|
|
|
Provider tokens are sent only over HTTPS on the default port (or 443): `github.com`, `gitlab.com`, `bitbucket.org`, `dev.azure.com`, `*.visualstudio.com`, `gitea.com`, and `cnb.cool`. Self-hosted Gitea/CNB requires an exact hostname in `gitea_hosts`/`cnb_hosts`, even if its name contains the provider name. For self-hosted GitHub/GitLab or other hosts, use a host-scoped Git credential helper, or set `SKILLSHARE_GIT_TOKEN` only for the intended invocation. That generic fallback can be sent to **any HTTPS source**; provider-looking names do not authorize provider tokens.
|
|
|
|
**Used for:**
|
|
- GitHub API requests (`skillshare search`, `skillshare upgrade`, version check)
|
|
- **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")
|
|
```
|
|
|
|
---
|
|
|
|
### GH_TOKEN
|
|
|
|
Alternative GitHub token variable. Used by the [GitHub CLI (`gh`)](https://cli.github.com/) and recognized by skillshare as a fallback.
|
|
|
|
**Token resolution order:** `GITHUB_TOKEN` → `GH_TOKEN` → `gh auth token`
|
|
|
|
If you already use `gh` and have authenticated via `gh auth login`, skillshare picks up the token automatically — no extra env vars needed.
|
|
|
|
```bash
|
|
export GH_TOKEN=ghp_your_token_here
|
|
skillshare search "react patterns"
|
|
```
|
|
|
|
---
|
|
|
|
## Git Authentication {#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
|
|
```
|
|
|
|
### AZURE_DEVOPS_TOKEN
|
|
|
|
Azure DevOps Personal Access Token (PAT). Used for HTTPS clone of Azure DevOps-hosted private repos.
|
|
|
|
**Creating a token:**
|
|
1. Go to `https://dev.azure.com/{org}/_usersSettings/tokens`
|
|
2. Select **+ New Token**
|
|
3. Scopes: **Code → Read** (pull only) or **Code → Read & Write** (push & pull)
|
|
4. Copy the token (84-character string with `AZDO` signature)
|
|
|
|
Official docs: [Use Personal Access Tokens](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops)
|
|
|
|
```bash
|
|
export AZURE_DEVOPS_TOKEN=your_pat_here
|
|
skillshare install https://dev.azure.com/org/project/_git/repo --track
|
|
```
|
|
|
|
**Windows:**
|
|
```powershell
|
|
$env:AZURE_DEVOPS_TOKEN = "your_pat_here"
|
|
```
|
|
|
|
### GITEA_TOKEN
|
|
|
|
Gitea access token. Used for HTTPS clone of private repos on `gitea.com` and self-hosted Gitea, and for the Gitea Contents API when a subdirectory is installed without a full clone.
|
|
|
|
**Creating a token:**
|
|
1. In Gitea, go to **Settings → Applications**
|
|
2. Generate a new token
|
|
3. Permissions: `repository: Read` (pull only) or `repository: Read and Write` (push & pull)
|
|
|
|
```bash
|
|
export GITEA_TOKEN=your_token
|
|
skillshare install https://gitea.com/org/skills.git --track
|
|
```
|
|
|
|
**Windows:**
|
|
```powershell
|
|
$env:GITEA_TOKEN = "your_token"
|
|
```
|
|
|
|
Self-hosted Gitea requires an exact hostname in [`gitea_hosts`](/docs/reference/targets/configuration#gitea_hosts) to authorize `GITEA_TOKEN`, even when the name contains `gitea`. Provider authentication requires HTTPS on the default port or 443.
|
|
|
|
### CNB_TOKEN
|
|
|
|
[CNB](https://cnb.cool) access token with read permission on the repository. Used for HTTPS clone of private repos on `cnb.cool` and self-hosted CNB.
|
|
|
|
```bash
|
|
export CNB_TOKEN=your_token
|
|
skillshare install https://cnb.cool/org/skills --track
|
|
```
|
|
|
|
**Windows:**
|
|
```powershell
|
|
$env:CNB_TOKEN = "your_token"
|
|
```
|
|
|
|
A private deployment on another domain needs [`cnb_hosts`](/docs/reference/targets/configuration#cnb_hosts).
|
|
|
|
### 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`, `AZURE_DEVOPS_TOKEN`, `GITEA_TOKEN`, `CNB_TOKEN`) > `SKILLSHARE_GIT_TOKEN`.
|
|
|
|
---
|
|
|
|
## Plugins {#plugins}
|
|
|
|
### SKILLSHARE_CODEX_CLI
|
|
|
|
The Codex CLI that [plugin commands](/docs/reference/commands/plugin) run, on this machine only. Set it when Skillshare cannot find Codex by itself. It is read from the environment, so a `config.yaml` shared between macOS and Windows does not need a path that is wrong on the other one.
|
|
|
|
Without it, Skillshare runs `codex` from `PATH`, then tries these places:
|
|
|
|
| OS | Places |
|
|
|---|---|
|
|
| macOS | `/opt/homebrew/bin/codex`, `/usr/local/bin/codex`, and the CLI inside the Codex app (`ChatGPT.app` or `Codex.app` in `/Applications` or `~/Applications`) |
|
|
| Windows | `%LOCALAPPDATA%\Programs\OpenAI\Codex\bin\codex.exe` from the official PowerShell installer, then the CLI the Codex app installs, `%LOCALAPPDATA%\OpenAI\Codex\bin\<version>\codex.exe` (the newest one) |
|
|
|
|
```bash
|
|
export SKILLSHARE_CODEX_CLI=/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex
|
|
```
|
|
|
|
**Windows:**
|
|
```powershell
|
|
$env:SKILLSHARE_CODEX_CLI = "C:\Tools\codex.exe"
|
|
```
|
|
|
|
An [account target](/docs/reference/commands/plugin#accounts) with its own `cli` keeps that `cli`.
|
|
|
|
---
|
|
|
|
## Git SSL / TLS {#git-ssl--tls}
|
|
|
|
These standard Git environment variables are passed through to all git operations. They are useful for self-hosted Git servers (GitLab, Gitea, etc.) with self-signed certificates or internal CAs.
|
|
|
|
### GIT_SSL_CAINFO
|
|
|
|
Path to a custom CA certificate bundle. Use this when your self-hosted Git server uses a certificate signed by an internal CA.
|
|
|
|
```bash
|
|
export GIT_SSL_CAINFO=/path/to/ca-bundle.crt
|
|
skillshare install https://gitlab.internal.company.com/team/skills.git --track
|
|
```
|
|
|
|
### GIT_SSL_NO_VERIFY
|
|
|
|
Disable SSL certificate verification entirely. Use as a last resort when CA certificate setup is not feasible.
|
|
|
|
:::warning Security risk
|
|
Disabling SSL verification makes connections vulnerable to man-in-the-middle attacks. Prefer `GIT_SSL_CAINFO` with a proper CA bundle, or use SSH instead.
|
|
:::
|
|
|
|
```bash
|
|
GIT_SSL_NO_VERIFY=true skillshare install https://gitlab.internal.company.com/team/skills.git --track
|
|
```
|
|
|
|
**Alternative: use SSH to avoid SSL entirely:**
|
|
```bash
|
|
skillshare install git@gitlab.internal.company.com:team/skills.git --track
|
|
```
|
|
|
|
---
|
|
|
|
## 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` |
|
|
| `SKILLSHARE_UI_BASE_PATH` | Web UI sub-path for reverse proxy | None |
|
|
| `SKILLSHARE_UI_TRUSTED_ORIGINS` | Web UI addresses besides localhost and IPs (comma-separated) | None |
|
|
| `SKILLSHARE_GITLAB_HOSTS` | Custom GitLab hostnames (comma-separated) | None |
|
|
| `SKILLSHARE_AZURE_HOSTS` | Custom Azure DevOps Server hostnames (comma-separated) | None |
|
|
| `SKILLSHARE_GITEA_HOSTS` | Custom Gitea hostnames (comma-separated) | None |
|
|
| `SKILLSHARE_CNB_HOSTS` | Custom CNB hostnames (comma-separated) | None |
|
|
| `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 project registrations and locks) | `~/.local/state` |
|
|
| `XDG_CACHE_HOME` | Cache directory (version check, UI) | `~/.cache` |
|
|
| `GITHUB_TOKEN` | GitHub API + git clone auth | None |
|
|
| `GH_TOKEN` | GitHub API (fallback for `GITHUB_TOKEN`) | None |
|
|
| `GITLAB_TOKEN` | GitLab git clone auth | None |
|
|
| `BITBUCKET_TOKEN` | Bitbucket git clone auth | None |
|
|
| `BITBUCKET_USERNAME` | Bitbucket username for app password auth | None |
|
|
| `AZURE_DEVOPS_TOKEN` | Azure DevOps git clone auth | None |
|
|
| `GITEA_TOKEN` | Gitea git clone + Contents API auth | None |
|
|
| `CNB_TOKEN` | CNB git clone + contents API auth | None |
|
|
| `SKILLSHARE_GIT_TOKEN` | Generic git clone auth (fallback) | None |
|
|
| `SKILLSHARE_CODEX_CLI` | Codex CLI for plugin commands on this machine | `codex` on `PATH`, then known install places |
|
|
| `GIT_SSL_CAINFO` | Custom CA certificate bundle path | System default |
|
|
| `GIT_SSL_NO_VERIFY` | Disable SSL certificate verification | `false` |
|
|
| `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
|