forge — the LuisForge command-line client

A single-file Python script, standard library only, no dependencies to install. Talks to the same API the website and mobile app use.

Install

Run this on Linux or macOS:

curl -fsSL https://luisforge.pages.dev/install.sh | bash

Installs to ~/.local/bin/forge and adds that directory to your PATH in .zshrc/.bashrc/.profile depending on your shell. Don't run it with sudo — it installs per-user, and root would put it in the wrong home directory entirely (see the installer's own warning if you try). Prefer to read it first? The script is at /install.sh, and the CLI source itself is at /forge.py.

Windows?

No. install.sh is a bash script (shell detection, ~/.local/bin, appending to .zshrc/.bashrc) and doesn't run on Windows outside of WSL. There's no install.ps1 or native Windows installer — if you're on WSL, just follow the Linux instructions above inside it.

Commands

Command	What it does
`forge auth signup` / `login` / `logout` / `whoami`	Account management
`forge clone <owner/repo> [dest]`	Clone a repo (works around the HTTP smart-protocol limitation — see docs)
`forge repos`	List repos you can see
`forge create <name> [--private] [--desc "..."]`	Create a repo
`forge delete <owner/repo>`	Delete a repo you own
`forge push <owner/repo> <local_file> [remote_path]`	Upload a single file as a commit
`forge files <owner/repo> [path]`	List a repo's files
`forge cat <owner/repo> <path>`	Print a file's contents
`forge log <owner/repo>`	Show commit history
`forge issues list` / `create`	Issue tracker
`forge run <owner/repo> "<cmd>" [--image alpine]`	One-shot command in a container
`forge cmd <owner/repo> "<cmd>" [--image alpine] [--port N]`	Host a long-running server publicly via bore
`forge cmd stop <owner/repo> <run_id>`	Stop a hosted server
`forge 2fa setup` / `verify` / `disable`	TOTP 2FA management
`forge ssh-key add` / `list` / `rm`	Manage SSH public keys for real `git clone`/`push`
`forge update`	Check for and install a newer version of forge itself
`forge update --force`	Re-download and reinstall regardless of whether a change is detected
`forge uninstall [--yes]`	Remove `~/.forge` (config + saved token), strip the PATH line the installer added, then delete forge (and codey, if installed)

codey — LuisCodey from the terminal

codey is a separate, standalone command (installed alongside forge by the same installer) for chatting with LuisCodey — the AI coding assistant — without leaving the terminal. It shares forge's login session (~/.forge/config.json), so no separate sign-in needed. By default it opens a full-screen TUI (built on Python's stdlib curses — no extra deps), with a centered logo/input box on an idle screen that transitions into a scrolling chat log once you start talking, similar in spirit to tools like OpenCode. Pass --plain for a plain-text REPL instead (useful over dumb pipes, logs, or terminals that don't support curses).

codey

Run it with no arguments to pick a repo from a full-screen, filterable list (type to filter, ↑/↓ to move, Enter to select) — or skip the picker with codey owner/repo to jump straight into chatting about a specific one.

Key / command	What it does
(just type, then Enter)	Send a message to LuisCodey — it knows the repo's current file list
`/save [n]`	Commit the n-th code block from the last reply (or the first, if omitted) straight into the repo, using the filename Codey specified
`/clear`	Reset conversation history — starts a fresh context
`Esc` / `Ctrl+C`	Quit

Requires AI to be turned on for that repo (Settings tab / per-repo toggle) — same requirement as the web and mobile LuisCodey chat. Source: /codey.py.

Keeping forge up to date

forge update downloads the latest forge.py from https://update.luisforge.pages.dev/forge.py — a separate Cloudflare Pages branch alias dedicated to serving update checks, kept stable and independent of both the main site's deploys and the backend's cloudflared tunnel URL (which isn't stable across restarts) — and compares its SHA-256 against the copy you have installed.

forge update — only replaces the installed script if the remote copy is actually different. If you're already current, it just prints Already up to date and does nothing.
forge update --force — skips the comparison and re-downloads/reinstalls unconditionally. Useful if you suspect your local install got corrupted, or you just want to be sure.

Both commands overwrite the script in place at whatever path it's actually running from (typically ~/.local/bin/forge) and keep it executable — no need to re-run the installer.

Config & credentials. forge stores its API base URL and your saved auth token at ~/.forge/config.json, created with 0600 permissions (owner read/write only) since it holds a live session token.

See also: full docs for how the backend, Cmd/Server tabs, and everything else forge talks to actually works.