Environment Variables

All environment variables recognized by skillshare.

Configuration

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).

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).

export XDG_CACHE_HOME=~/my-cache
# skillshare will use ~/my-cache/skillshare/

Default: ~/.cache/skillshare/

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.

GitHub API

GITHUB_TOKEN

GitHub personal access token.

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: repo for 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) or read_repository + write_repository (push & pull)
Copy the token (prefix glpat-)

Official docs: Token overview

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-auth automatically (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 as https://<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 AZDO signature)

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) or repository: 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"

The token is sent only to the host you install from. A self-hosted instance on a domain without gitea in its name needs gitea_hosts, otherwise SKILLSHARE_GIT_TOKEN is used for it.

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.

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 [email protected]: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_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/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`

Configuration — Config file reference
Windows Issues — Windows environment setup

Configuration​

SKILLSHARE_CONFIG​

XDG_CONFIG_HOME​

XDG_DATA_HOME​

XDG_STATE_HOME​

XDG_CACHE_HOME​

SKILLSHARE_GITLAB_HOSTS​

SKILLSHARE_AZURE_HOSTS​

SKILLSHARE_GITEA_HOSTS​

SKILLSHARE_CNB_HOSTS​

Web UI​

SKILLSHARE_UI_BASE_PATH​

GitHub API​

GITHUB_TOKEN​

GH_TOKEN​

Git Authentication​

GITLAB_TOKEN​

BITBUCKET_TOKEN​

BITBUCKET_USERNAME​

AZURE_DEVOPS_TOKEN​

GITEA_TOKEN​

CNB_TOKEN​

SKILLSHARE_GIT_TOKEN​

Plugins​

SKILLSHARE_CODEX_CLI​

Git SSL / TLS​

GIT_SSL_CAINFO​

GIT_SSL_NO_VERIFY​

Testing​

SKILLSHARE_TEST_BINARY​

Usage Examples​

Temporary override​

Permanent setup (macOS/Linux)​

Permanent setup (Windows)​

Summary​

Related​

Configuration

SKILLSHARE_CONFIG

XDG_CONFIG_HOME

XDG_DATA_HOME

XDG_STATE_HOME

XDG_CACHE_HOME

SKILLSHARE_GITLAB_HOSTS

SKILLSHARE_AZURE_HOSTS

SKILLSHARE_GITEA_HOSTS

SKILLSHARE_CNB_HOSTS

Web UI

SKILLSHARE_UI_BASE_PATH

GitHub API

GITHUB_TOKEN

GH_TOKEN

Git Authentication

GITLAB_TOKEN

BITBUCKET_TOKEN

BITBUCKET_USERNAME

AZURE_DEVOPS_TOKEN

GITEA_TOKEN

CNB_TOKEN

SKILLSHARE_GIT_TOKEN

Plugins

SKILLSHARE_CODEX_CLI

Git SSL / TLS

GIT_SSL_CAINFO

GIT_SSL_NO_VERIFY

Testing

SKILLSHARE_TEST_BINARY

Usage Examples

Temporary override

Permanent setup (macOS/Linux)

Permanent setup (Windows)

Summary

Related