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.
17 KiB
sidebar_position
| sidebar_position |
|---|
| 2 |
Environment Variables
All environment variables recognized by skillshare.
Configuration
SKILLSHARE_AUTO_UPDATE_CHECK
Override global updates.auto_check for automatic release-version checks and notifications.
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; upgrading
the CLI alone does not disable checks in older desktop builds. See updates.
SKILLSHARE_CONFIG
Override the config file path.
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.
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).
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).
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.
XDG_CACHE_HOME
Override the cache directory (version check cache, UI dist cache).
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.
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 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.
SKILLSHARE_AZURE_HOSTS=azuredevops.mycompany.com,tfs.internal.io
When both the env var and config file 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.
SKILLSHARE_GITEA_HOSTS=git.company.com,code.internal.io
Merged with the config file's gitea_hosts.
Default: (none)
SKILLSHARE_CNB_HOSTS
Comma-separated list of self-hosted CNB hostnames. cnb.cool is detected without it.
SKILLSHARE_CNB_HOSTS=cnb.company.com
Merged with the config file's cnb_hosts.
Default: (none)
Web UI
SKILLSHARE_UI_BASE_PATH
Set the URL sub-path for serving the web dashboard behind a reverse proxy.
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 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.
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.
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:
- Go to https://github.com/settings/tokens
- Generate new token (classic)
- Scope:
repofor private repos, none for public repos - Copy the token
Official docs: Managing your personal access tokens
Usage:
export GITHUB_TOKEN=ghp_your_token_here
skillshare install https://github.com/org/private-skills.git --track
Windows:
# 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) 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.
export GH_TOKEN=ghp_your_token_here
skillshare search "react patterns"
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 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:
- Go to https://gitlab.com/-/user_settings/personal_access_tokens
- Add new token
- Scopes:
read_repository(pull only) orread_repository+write_repository(push & pull) - Copy the token (prefix
glpat-)
Official docs: Token overview
:::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.
:::
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
skillshare install https://gitlab.com/org/skills.git --track
Windows:
$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):
- Go to Repository → Settings → Access tokens
- Create token with Read permission (pull only) or Read + Write (push & pull)
- Copy the token — uses
x-token-authautomatically (no username needed)
Creating a token (app password):
- Go to https://bitbucket.org/account/settings/app-passwords/
- Create app password with Repositories: Read (pull only) or Repositories: Read + Write (push & pull)
- Also set
BITBUCKET_USERNAME(or include it in the URL ashttps://<username>@bitbucket.org/...)
Official docs: Access tokens
export BITBUCKET_USERNAME=your_bitbucket_username
export BITBUCKET_TOKEN=your_app_password
skillshare install https://bitbucket.org/team/skills.git --track
Windows:
$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.
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:
- Go to
https://dev.azure.com/{org}/_usersSettings/tokens - Select + New Token
- Scopes: Code → Read (pull only) or Code → Read & Write (push & pull)
- Copy the token (84-character string with
AZDOsignature)
Official docs: Use Personal Access Tokens
export AZURE_DEVOPS_TOKEN=your_pat_here
skillshare install https://dev.azure.com/org/project/_git/repo --track
Windows:
$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:
- In Gitea, go to Settings → Applications
- Generate a new token
- Permissions:
repository: Read(pull only) orrepository: Read and Write(push & pull)
export GITEA_TOKEN=your_token
skillshare install https://gitea.com/org/skills.git --track
Windows:
$env:GITEA_TOKEN = "your_token"
Self-hosted Gitea requires an exact hostname in 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 access token with read permission on the repository. Used for HTTPS clone of private repos on cnb.cool and self-hosted CNB.
export CNB_TOKEN=your_token
skillshare install https://cnb.cool/org/skills --track
Windows:
$env:CNB_TOKEN = "your_token"
A private deployment on another domain needs cnb_hosts.
SKILLSHARE_GIT_TOKEN
Generic fallback token for any HTTPS git host. Used when no platform-specific token is set.
export SKILLSHARE_GIT_TOKEN=your_token
skillshare install https://git.example.com/org/skills.git --track
Windows:
$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
SKILLSHARE_CODEX_CLI
The Codex CLI that plugin commands 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) |
export SKILLSHARE_CODEX_CLI=/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex
Windows:
$env:SKILLSHARE_CODEX_CLI = "C:\Tools\codex.exe"
An account target with its own cli keeps that cli.
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.
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.
:::
GIT_SSL_NO_VERIFY=true skillshare install https://gitlab.internal.company.com/team/skills.git --track
Alternative: use SSH to avoid SSL entirely:
skillshare install git@gitlab.internal.company.com:team/skills.git --track
Testing
SKILLSHARE_TEST_BINARY
Override the CLI binary path for integration tests.
SKILLSHARE_TEST_BINARY=/path/to/skillshare go test ./tests/integration
Default: bin/skillshare in project root
Usage Examples
Temporary override
# 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:
export GITHUB_TOKEN="ghp_your_token_here"
Permanent setup (Windows)
[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 — Config file reference
- Windows Issues — Windows environment setup