Jevwise

A Go SDK for TypeSafe AI and the jevwise decision CLI.

Installation

Homebrew

brew tap benbenbang/forge
brew install jevwise

• On Homebrew versions requiring explicit tap trust, or to avoid formula-name collisions, use brew install benbenbang/forge/jevwise. This selects and trusts only that formula: see Homebrew tap trust.
• Manage Homebrew installations with brew upgrade jevwise, not the standalone self-updater or install script's --force option.

GitHub install script (macOS/Linux)

Latest stable release, installed as ~/.local/bin/jevwise:

curl -fsSL https://raw.githubusercontent.com/bitbrew-dev/jevwise/main/scripts/install.sh | sh -s --
# Pin a release and choose a writable directory:
curl -fsSL https://raw.githubusercontent.com/bitbrew-dev/jevwise/main/scripts/install.sh | sh -s -- --version v1.2.3 --dir "$HOME/bin"
# From a checkout, without piping remote shell code:
sh scripts/install.sh --version latest --dir "$HOME/.local/bin"

• --version latest is the default; pinned versions must be canonical stable vX.Y.Z tags. Latest selection uses GitHub's public release redirect, not the anonymous REST API quota. Private releases require manual authenticated downloads.
• --dir PATH selects the installation directory, including relative paths. The default is $HOME/.local/bin, not /usr/local/bin. Add it to PATH yourself if needed.
• Requires macOS/Linux amd64/arm64, POSIX sh, curl 8.4+, standard Unix utilities and sha256sum or shasum. Windows installation remains manual.
• Existing files are preserved unless --force is supplied. Replacement requires a regular, nonsymlink executable owned by the current user. A pinned install with --force can downgrade; use your package manager for managed installations.
• Exact platform assets are verified against bounded SHA256SUMS before same-directory publication. Legacy jev_... assets are supported only when the manifest lacks the new name, never after a failed download/hash check. Older binaries retain their original branding and behavior even when installed as jevwise.
• The script uses no sudo, modifies no shell/config/agent settings, and never executes the downloaded binary. Restart running MCP servers after replacement. Cooperating installers/updaters share a lock; stale locks require manual inspection.
• Trust the repository, GitHub/TLS, local tools and installation parents. Final directory symlinks and world-writable directories are refused; hostile concurrent writers and power-loss durability are not supported. Checksums detect corruption, not a compromised publisher.
• Piping executes remote code before you can inspect it. Prefer downloading and reviewing the script first, and pin its URL to a trusted commit/tag when reproducibility matters. The script itself is not authenticated by the binary checksum. The public URL becomes available when this change lands on main.

Manual GitHub download

Download a binary and SHA256SUMS from GitHub Releases. Choose your platform and verify the SHA-256 checksum before installation.

Platform	Architectures	Asset pattern
Linux	amd64, arm64	jevwise_vX.Y.Z_linux_ARCH
macOS	amd64, arm64	jevwise_vX.Y.Z_darwin_ARCH
Windows	amd64, arm64	jevwise_vX.Y.Z_windows_ARCH.exe

• Install Unix binaries as jevwise in a directory on PATH and make them executable. Windows users install as jevwise.exe in a directory on PATH.
• Releases through v1.2.0 retain legacy jev_... filenames and original branding. No jev alias is installed; verify ownership before removing an old binary belonging to another project.
• Checksums detect corruption, not a compromised publisher. See release assets and verification for details.
• Prefer building from source? Follow the development guide.

Authentication

Supply credentials through a secured environment or protected files, not secret-valued command-line arguments. These names describe the current checkout.

Default environment variable	Purpose
JEV_API_KEY	Upstream Jev API access for decisions and the MCP server's backend
GOOGLE_API_KEY, then GEMINI_API_KEY	Google Gemini Decisions API access when the gemini provider is selected
JEVWISE_MCP_TOKEN	Optional override for local MCP authentication; otherwise generated and privately stored

Providers

Provider	Service	Key
jev (default)	TypeSafe Jev API	JEV_API_KEY
gemini	Google Gemini Decisions API (gemini-decision-1)	GOOGLE_API_KEY, then GEMINI_API_KEY
codex, claude	Reserved, not implemented

Select one per call with --provider gemini, or for every call with provider = "gemini" under [general] in your configuration. Each provider reads only its own keys, so a Jev key never reaches Google and the reverse. See configuration.

Upstream API key

Set JEV_API_KEY in your secured environment, or reference any exported variable in your selected TOML configuration:

[provider.jev]
api_key = "$ABCD_TOKEN"
# Equivalent: api_key = "${ABCD_TOKEN}"

• ABCD_TOKEN is only an example; custom names such as JEV_MCP_API_KEY also work. Export the referenced variable before starting Jevwise.
• Only the TOML api_key expands environment references. Unset variables expand to empty; Jev service initialization requires a nonblank key.
• Changed --api-key flags override nonblank API environment values, which override TOML. Direct environment and flag values stay literal.
• API fallback names, in order: JEVWISE_API_KEY, TS_JEV_API_KEY, TYPESAFE_API_KEY. The standalone Go SDK retains TYPESAFE_API_KEY as its environment fallback. See configuration.

Google API key

Jevwise sends the key in the x-goog-api-key header; it does not use OAuth or Application Default Credentials (ADC) at runtime. Get a key in one of two ways:

Way	Best for	How
1. Personal (AI Studio)	Trying it out, personal use	Sign in at aistudio.google.com/api-keys and create a key. AI Studio sets up a Google Cloud project if you have none.
2. Organization project (Terraform)	Teams, billing and key restrictions under an organization	Use ADC once to let Terraform enable the Gemini API, link billing and create a key restricted to generativelanguage.googleapis.com. Follow Google API key via Terraform.

export GEMINI_API_KEY='...'   # or GOOGLE_API_KEY, which wins if both are set
jevwise decide --provider gemini --prompt "What is 2 + 2?" --option 4 --option 5

• Restrict the key to the Generative Language API, and keep it out of command arguments and stored files, like the Jev key.
• A paid project needs a positive Gemini prepaid balance in AI Studio; at $0 its keys stop working. See the Terraform guide.
• Work accounts may block key creation by organization policy; the error names the constraint.

Local MCP authentication

• Use a separate bearer token: never reuse the upstream API key or give it to the agent.
• With no token override, jevwise mcp generates a random token in <runtime-dir>/agent.token and reuses it across restarts. Only your upstream API key needs manual setup.
• jevwise mcp token-path prints the automatic file path, never the secret; see agent onboarding to load it into the client environment.
• Register the installed client with jevwise mcp install codex or jevwise mcp install claude. Both default to user-wide settings; custom ports use --listen IP:PORT or port under [mcp] in configuration. Registration stores only an environment reference, not the token. See agent onboarding.
• Overrides take precedence: --token-file /path/to/protected/agent-token > JEVWISE_MCP_TOKEN (including aliases) > automatic token. Explicit values are never copied into the automatic file.
• MCP fallback names, in order: JEVWISE_MCP_AUTH_TOKEN, JEV_MCP_TOKEN. Invalid nonempty tokens fail without fallback; tokens must be printable ASCII without whitespace.
• Keep secrets out of shell history, logs and stored agent configuration. Follow local MCP setup and agent onboarding for protected files and client environment references.

Documentation

Guide	Contents
CLI usage	Decisions and skill setup
Configuration	Precedence, API keys, providers, local config and editor
Google API key via Terraform	Organization project key for the Gemini provider
Go SDK	Quickstart, request options and retries
Development	Source builds, platform builds and tests
Debugging	Debug logging and safe diagnostics
Updates	Release checks, self-update and replacement safety
Releases	Assets, verification and publication
Local MCP	Foreground/background mode, credentials and limits
Agent onboarding	Connect Codex or Claude Code safely