gujoctl

gujoctl is a single executable for macOS and Linux. It signs you in with browser approval, lists your library, and downloads, verifies and installs products you bought.

Install

curl -fsSL "https://gujo.ai/download/gujo-install.sh?channel=dev" | sh

The install script fetches the latest release of that channel for your platform (darwin-arm64, darwin-amd64, linux-amd64 or linux-arm64), checks its sha256 and puts it in ~/.local/bin. Set GUJOCTL_BIN_DIR to use another folder.

The dev channel is the one open today. The address without a channel (stable) is still closed.

Sign in

gujoctl login

1. gujoctl shows a user code and opens the approval page on the account host in your browser.
2. Signed in to your Gujo account in the browser, check the code and approve it.
3. gujoctl waits for the approval, then receives and stores an account API key.

On a server that cannot open a browser, use gujoctl login --no-browser. It prints the page and the code, and you approve from a browser on another device.

The key you get is a device sign-in key with six abilities: products.read, device.entitlements, device.activate, device.install, device.usage and support.report. It has no mcp.read. To connect an agent over MCP, create a separate key as described in Getting started.

The key is kept in the device's standard secret store: Keychain on macOS, secret-service on Linux (when a session bus is available), and otherwise a file with mode 600.

Commands

Command	What it does
gujoctl login [--no-browser]	Device sign-in. Shows a code and waits for browser approval
gujoctl logout	Revokes this device's key on the server and deletes it from the device
gujoctl library list	Lists the products you can use (numeric ids)
gujoctl install <id> [--channel <c>] [--dir <path>]	Gets an install plan, downloads, checks the sha256 and unpacks
gujoctl version	Version, commit, OS and architecture
gujoctl help	Usage

Global flags:

• --json: writes only JSON to stdout. Progress messages go to stderr.
• --api-url <url>: changes the API address. The default is https://api.gujo.ai, and GUJO_API_URL sets it too.

Installing a product

gujoctl library list
gujoctl install 42

install gets the server's install plan (GET /api/products/{id}/install), downloads the file from the signed download URL, and refuses to unpack it if the sha256 differs. Pick a channel with --channel stable|beta|alpha|dev. Without it you get stable. Where the product goes depends on the target the server reports.

Target	Where it goes
agent-skill (agent skill, tar.gz)	--dir or INSTALL_DIR. Otherwise skills/<name> in the first of ~/.claude, ~/.codex and ~/.gemini/antigravity-cli that exists, ./.agents/skills/<name> inside a repository, and ~/.local/share/gujo/assets/<name> as the last resort
macos-app (app, zip)	Moves the single .app to /Applications (or ~/Applications if that is not writable), or to --dir

An existing install is removed only after the new one is in place. Absolute paths, .. and symbolic links pointing outside the archive are rejected. The key goes to the API host only, never to the download URL.

Settings and environment variables

Variable	Meaning
GUJO_API_URL	API address (same as --api-url)
GUJOCTL_SECRET_STORE	Secret store choice: keychain, secret-service or file
GUJOCTL_CONFIG_DIR	Config folder. The default is ~/.config/gujoctl

config.json in the config folder holds only non-secret sign-in details. With the file store, the key goes in credentials.json in the same folder.

Exit codes

Code	Meaning
0	Success
1	Error
2	Usage
3	Sign-in required (401)
4	Forbidden (403)

In scripts, exit code 3 means the user should run gujoctl login again.