wiswa

A highly opinionated way to generate projects with Jsonnet.

Installation

We recommend a global install so wiswa and wiswa-mcp are on your PATH from any working directory:

uv tool install wiswa

Or with pipx:

pipx install wiswa

If you prefer not to install globally, add Wiswa as a development dependency of your project—for example uv add --group dev wiswa, or list wiswa under dependency-groups.dev in pyproject.toml and install inside the project virtual environment with your usual workflow.

Usage

Add -d to show debug logs.

Usage: wiswa [OPTIONS] [FILE]

  Entry point for the Wiswa CLI.

Options:
  --cache-time INTEGER            Cache expiry time in seconds.  [default:
                                  600]
  -d, --debug                     Enable debug output.
  -J, --jpath TEXT                Add a directory to the Jsonnet search path
                                  (only used when evaluating settings).
  --no-cache                      Disable HTTP response caching.
  -o, --output-dir DIRECTORY      Output directory for generated files.
  -q, --quiet                     Suppress the progress spinner.
  --skip-jsonnet                  Skip project.jsonnet manifests; settings merge still runs.
  --skip-postprocess              Skip post-processing steps.
  --skip-remote                   Skip configuring the remote Git host (GitHub or GitLab).
  --skip-static                   Skip copying static files.
  --skip-templates                Skip Jinja2 template evaluation.
  --skip-yarn                     Skip Yarn download.
  -h, --help                      Show this message and exit.

Remote API tokens (GitHub and GitLab)

When Wiswa configures the remote (wiswa without --skip-remote), it calls the GitHub or GitLab API using a personal access token. Tokens are read from the environment when supported, or from the system keyring. Service names include the repository hostname so different hosts (for example GitHub.com, GitHub Enterprise, or self-managed GitLab) keep separate credentials.

Keyring entries use the usual service name and username fields (for example as shown by secret-tool on Linux or Keychain Access on macOS). The username is normally your OS login name (whoami).

GitHub

1. Service wiswa-github:<hostname>, username your OS user. The hostname is taken from repository_uri (for example github.com for https://github.com/org/repo).

Example (hostname github.com, OS user alice):

python -m keyring set 'wiswa-github:github.com' alice
# paste the token at the prompt

GitLab

1. Environment: GITLAB_TOKEN (if set, used first).
2. Preferred: service wiswa-gitlab:<hostname>, username your OS user (for example wiswa-gitlab:gitlab.com).
3. Same service with username equal to the hostname is also checked (for older or alternate storage patterns).

Example for gitlab.com:

export GITLAB_TOKEN='glpat-...'   # optional; overrides keyring

python -m keyring set 'wiswa-gitlab:gitlab.com' "$(whoami)"

MCP Server

Wiswa includes an MCP server (wiswa-mcp) that exposes settings discovery tools for AI assistants.

Claude Code

claude mcp add wiswa-mcp -- wiswa-mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "wiswa-mcp": {
      "command": "wiswa-mcp"
    }
  }
}

GitHub Copilot CLI

Add to .github/copilot/mcp.json:

{
  "mcpServers": {
    "wiswa-mcp": {
      "command": "wiswa-mcp"
    }
  }
}