Files
skillshare/website/docs/reference/appendix/environment-variables.md
T
Willie 70cb287672 fix(plugin): find the Codex CLI the desktop app ships (#383)
* fix(plugin): find the Codex CLI the desktop app ships

Plugin commands ran the bare name `codex` from PATH, so a machine with only
the Codex desktop app, or a scheduled job started with a minimal PATH,
reported the CLI as missing. The account-only `cli` override did not help:
the default codex target cannot set it, and an absolute path in a config
shared between macOS and Windows is wrong on one of them.

When `codex` is not on PATH, look in Homebrew's folders and the CLI the app
installs (Codex.app on macOS, %LOCALAPPDATA%\OpenAI\Codex\bin on Windows).
SKILLSHARE_CODEX_CLI overrides the search on one machine without touching
the synced config. The missing-CLI error now lists every place searched, in
the CLI and the dashboard.

Refs #338

* docs(plugin): note where Skillshare finds the Codex CLI

The plugin reference and the sharing guide still said every native CLI must
be on PATH, and the built-in skill told agents a missing CLI has no
fallback. Codex now has one, plus a machine-local override that agents
should prefer over a path in a shared config.

Refs #338

* fix(plugin): look for the Codex CLI inside ChatGPT.app

Since the Codex desktop app merged with ChatGPT, macOS installs it as
ChatGPT.app, so an app-only Mac with a minimal PATH still reported Codex as
missing. Try ChatGPT.app before Codex.app in /Applications and
~/Applications, the order Codex's own desktop-app finder uses.

Refs #338

* fix(plugin): run the packaged CLI entrypoint of the ChatGPT app

ChatGPT Desktop 26.924 removed Contents/Resources/codex and ships the CLI
at the entrypoint its package manifest declares, codex-cli/bin/codex, so a
current app-only Mac still reported Codex as missing. Try that entrypoint
first in each app bundle and keep the old path for earlier builds.

Refs #338

* fix(plugin): find the Codex CLI from the Windows installer

The official PowerShell installer puts codex.exe in
%LOCALAPPDATA%\Programs\OpenAI\Codex\bin and adds it to the user PATH. A job
started without that PATH missed it, the same gap Homebrew's folders cover
on macOS. Try it before the desktop app's copy.

Refs #338

* fix(plugin): keep an account's cli even when it is codex

The Codex search ran whenever the executable was the bare name codex, so an
account that set cli: codex could get SKILLSHARE_CODEX_CLI or the app's CLI
instead, against the documented rule that an account's own cli is kept.
Search only when no account cli is set.

Refs #338
2026-10-04 15:16:14 +08:00

15 KiB

sidebar_position
sidebar_position
2

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/

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


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:

  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

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:

  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

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

  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

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:

  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

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:

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

:::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_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