Forgehand CLI

Start CPU/GPU sessions, connect over SSH, expose ports, and install skills for team LLM access on Forgehand.

Install

Requires Node.js 24 or newer and npm. SSH connections also require an ssh client on your PATH.

npm install -g @qforge/forgehand
fh --version
fh login

The package installs both fh and forgehand. You can also run it without a global installation:

npx @qforge/forgehand --help

No repository access, Bun, TypeScript compiler, or AWS credentials are needed to use the CLI.

Use

fh login asks for your email and the six-digit code sent to your inbox. It saves a personal access token for subsequent commands. You can also use an existing token from Forgehand Settings:

fh login --token <your-personal-access-token>
fh whoami
fh ssh-key add                       # reads ~/.ssh/id_ed25519.pub
fh ssh-key ls
fh workspaces
fh classes
fh workspace create <team-slug> <workspace-name>
fh session start <workspace-name-or-id> --class gpu-l4 --wait
fh session ls
fh session ssh <session-id>
fh session jupyter <session-id>
fh port expose <session-id> 7860 --public
fh session stop <session-id>

A workspace holds persistent files; starting a session incurs compute usage until it stops. Available classes and team allowances are set by your platform administrator. --wait waits for the platform's running state; the first image pull and environment startup may still be finishing.

Use fh --help for the command list and --json for machine-readable responses. Workspace references accept a name, team-slug/name, or ID prefix. Session references accept an ID or unambiguous ID prefix. Port exposure is team-only unless you pass --public.

To set up SSH access, use an existing default key pair if you have one. Otherwise, generate an Ed25519 pair with ssh-keygen -t ed25519 without overwriting any existing key. Upload only the public .pub file with fh ssh-key add [public-key-file]; use --label NAME to name it. fh ssh-key rm <key-id> removes a registered key. Sign in to the CLI first if you are still on the browser's SSH-key onboarding screen, then return to that page after adding the key.

Team LLM API

Call gpt-6-sol and gpt-6-luna using the OpenAI SDK with your Forgehand access token. Both use a shared team prepaid USD balance; credits never expire and are separate from compute spending. A team organizer can help you obtain credits. No GPU session, workspace, SSH key, or Azure credentials are needed.

1. Create a personal access token in Settings and supply it to your application as the secret environment variable FORGEHAND_TOKEN. fh login saves a CLI token but does not export it to other programs.
2. Find the team's UUID with fh whoami --json and set FORGEHAND_TEAM_ID.
3. Check available credits and token usage on the Usage page.

With the openai Python package installed:

import os
from openai import OpenAI

origin = os.getenv("FORGEHAND_URL", "https://app.forgehand.app").rstrip("/")
team = os.environ["FORGEHAND_TEAM_ID"]
client = OpenAI(
    api_key=os.environ["FORGEHAND_TOKEN"],
    base_url=f"{origin}/api/v1/teams/{team}/llm/v1",
    max_retries=0,
)
response = client.responses.create(
    model="gpt-6-luna",  # or gpt-6-sol
    input="Explain Bell states in two sentences.",
    reasoning={"effort": "none"},
    max_output_tokens=256,
)
print(response.output_text)

Responses and Chat Completions support streaming, text, custom function tools, and structured JSON outputs. Images/files, hosted tools, stored response IDs, background jobs, and alternate service tiers are not supported. Requests have a 950 KB text/function payload limit, 32,768 output-token limit, and three-minute upstream timeout. Set an explicit output limit; it includes reasoning tokens.

Each call reserves credit before contacting Azure, then settles the reported token usage at the model's configured rates. HTTP 429 limit_reached means insufficient available credit. Ambiguous failures retain holds: check Usage before retrying and contact support with the request ID for uncertain charges. No automatic SDK retries are enabled in the example. The CLI currently has no fh llm commands; use the SDK or HTTP API.

GET /api/v1/teams/<TEAM_UUID>/llm/usage returns grants, balances, per-model token totals, and recent requests (authenticate with Authorization: Bearer <FORGEHAND_TOKEN>). Monetary values are micro-USD. The bundled forgehand-llm skill contains streaming examples and troubleshooting.

Agent skills

The CLI package includes eight skills covering the user-facing Forgehand workflows on the web and in the CLI: account setup, teams, workspaces, sessions, connections and ports, secrets, usage, and the LLM API. They do not include platform administration. Install them without signing in:

fh skills list
fh skills install                    # Codex: ~/.codex/skills (or $CODEX_HOME/skills)
fh skills install --agent claude     # Claude Code: ~/.claude/skills
fh skills install --project          # Codex: .codex/skills in the current directory
fh skills install --dir /path/to/skills

For a project-local Claude Code install, add --agent claude --project. For another agent, --dir takes the directory that contains individual skill folders. Re-running the command skips identical skills. If an installed skill has been changed, the command stops without overwriting it; use --force to replace bundled SKILL.md files after reviewing local changes. To get these LLM instructions from an older release, run npm install -g @qforge/forgehand@latest, then fh skills install --force (or add --agent claude for Claude Code). Restart the agent session to discover new skills.

Configuration

The default server is https://app.forgehand.app. Use fh login --url <url> for another Forgehand instance. Configuration is saved to $XDG_CONFIG_HOME/forgehand/config.json, or ~/.config/forgehand/config.json when XDG_CONFIG_HOME is unset. The directory and file are created with modes 0700 and 0600 on POSIX systems.

Environment overrides:

• FORGEHAND_URL: server URL.
• FORGEHAND_TOKEN: personal access token (use a secret environment variable in automation).
• FORGEHAND_CONFIG_DIR: alternate configuration directory.

To revoke access, delete the corresponding token in Forgehand Settings → Access tokens.

License

MIT. This license covers the CLI package; it does not license the hosted Forgehand service or backend.