Forgefy CLI (initial release)

A Python 3.11+ coding-assistance CLI. Language-independent prompts support writing, debugging, reviewing, testing, refactoring and planning code. Quality and language coverage depend on the selected model; no model is guaranteed to be best at everything.

Install

No Python required — installs a standalone forgefy binary and puts it on your PATH, the same way Ollama's or Claude Code's installer does:

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/Polybamz/forgefy-cli/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/Polybamz/forgefy-cli/main/install.ps1 | iex

Already have Python? pip/pipx work too — prefer pipx over plain pip, since pip install can silently install to a user directory that isn't on your PATH:

pipx install forgefy-cli

Either way, open a new terminal and you should have the forgefy command:

forgefy --help
forgefy config --init
forgefy providers
forgefy skills
forgefy doctor

Developing locally

git clone https://github.com/Polybamz/forgefy-cli.git
cd forgefy-cli
pip install -e ".[dev]"

Local and hosted models

With Ollama running and a model installed, list exact IDs and choose one:

forgefy models --provider ollama
forgefy run "Write a Rust function with unit tests that validates an email address" --provider ollama --model YOUR_INSTALLED_MODEL

For OpenRouter, set OPENROUTER_API_KEY in your environment, list models, then select an exact available ID. Free-tier models and availability are provider-controlled; verify pricing before sending requests. Local inference has hardware/energy costs.

forgefy models --provider openrouter
forgefy run "Explain this Python module and suggest tests" --provider openrouter --model YOUR_MODEL_ID --workspace 'C:\Users\USER\Desktop\polycarp\forgefy-cli' --file src/forgefy_cli/context.py --skill review

Built-in profiles: Ollama, OpenAI, OpenRouter, DeepSeek and Groq. Anthropic and Gemini models can be used through OpenRouter when offered there; native Anthropic/Gemini protocols are not implemented. No automatic provider or paid-model fallback occurs. Compatibility requires the /models and /chat/completions endpoints; a listed model is not necessarily a compatible text-generation model.

Provider plugins

forgefy config prints the config path (normally your home directory's .forgefy/config.toml). FORGEFY_CONFIG can select an alternate file. Add declarative OpenAI-compatible provider profiles:

default_provider = "local_server"
default_model = "your-model-id"

[providers.local_server]
base_url = "http://localhost:1234/v1"
api_key_env = ""

[providers.company]
base_url = "https://models.example.com/v1"
api_key_env = "COMPANY_MODEL_KEY"

Never store keys directly in configuration. Custom profiles cannot override built-in names. HTTPS is required for non-loopback endpoints. Only configure servers you trust: the chosen server receives your prompt, explicit file context, and its configured key. These plugins are configuration, not executable Python code or an MCP integration.

Skills and context

Choose --skill code|debug|review|test|refactor|plan. Repeat --skill-file to include trusted UTF-8 Markdown instructions. Repeat --file to send workspace-relative source files. Use a prompt of - for standard input. No repository files are sent implicitly. Files must resolve within the workspace. Common credential paths are excluded, but this is not a secret scanner: review every file and prompt before sending. Requests have a 120,000-character input cap; individual models may require much smaller inputs.

Interactive chat

& 'C:\Users\USER\Desktop\polycarp\.venv\Scripts\forgefy.exe' chat --provider ollama --model llama3:latest

Chat retains conversation history for follow-up questions. /new clears it, /help lists commands, and /exit or /quit ends the session. EOF exits normally; Ctrl+C cancels. Each request resends retained history, so hosted-provider usage can grow each turn. No automatic paid fallback occurs. Oldest complete user/assistant pairs are omitted when conversational content exceeds 120,000 characters; system/skill instructions are additional. This is a character cap, not a token budget. Failed requests preserve prior history. Chat accepts single-line turns and skill plugins; explicit --file context is currently supported by run only.

Replies stream to the terminal as they're generated by default; --no-stream waits for the complete response instead (both chat and run).

Every session is saved to disk under --session NAME (default "default", ~/.forgefy/history/NAME.json, permissioned 0600 where the OS supports it — override the directory with FORGEFY_HISTORY_DIR). A fresh run always starts empty, even under a name that already has history — add --resume to load that session's prior turns first. --no-history skips saving entirely, for a fully ephemeral session like older versions of this CLI. Session files can contain source code and other workspace content pasted into the conversation; they're local-only and never uploaded anywhere by this tool.

Approved file editing

forgefy edit can modify explicitly selected, existing UTF-8 files with a model supporting OpenAI-compatible tool calling. run and chat remain suggestion-only. In an interactive terminal, for example:

& 'C:\Users\USER\Desktop\polycarp\.venv\Scripts\forgefy.exe' edit "Improve error handling in this module" --provider ollama --model YOUR_TOOL_CALLING_MODEL --workspace 'C:\Users\USER\Desktop\polycarp\forgefy-cli' --file src/forgefy_cli/context.py

Review the selected files for secrets before starting: the model can read their contents and send them to the selected provider without further read approval. Each replacement shows a complete diff and requires typing yes. There is no automatic approval flag. The executor requires a prior read, an exact single match, and unchanged contents before and after approval. Updates use a sibling temporary file and atomic replacement.

Only files named by repeatable --file options are accessible. Hidden paths, common credential files, symlinks, junctions, hardlinks and nonregular files are rejected. Files and replacements are limited to 32,000 bytes; oversized diffs are rejected, not truncated for approval. These checks are not a secret scanner or an OS security sandbox. Use a trusted workspace without concurrent writers: a small filesystem race window remains between validation and replacement. Atomic replacement preserves mode bits, not necessarily all filesystem metadata or custom ACLs.

The default limit is 12 model requests (--max-turns accepts 1–30), with a 120,000-character serialized conversation cap. Exit code 2 means a limit stopped an incomplete session; 1 indicates an error and 130 indicates cancellation. Exit code 0 means the model finished, not that its changes are correct or tested. Applied edits remain on disk if the session stops or fails—there is no session-wide rollback. Use version control or backups and review the printed list of files actually changed.

Editing currently supports replacements and, with --allow-commands, running shell commands — no file deletion or custom skill files yet. Its integration tests use mocked model responses and temporary files; live model-driven editing has not been verified.

Running commands (--allow-commands)

Off by default. With it, the model gains a run_command tool — use it to build, lint, or run tests on the files it just edited, closing the loop that used to require you to verify changes yourself. The safety model is identical to file edits: the model proposes one exact command, you see it and the working directory, and must type yes before anything runs. It is not a sandbox — an approved command runs with your full user privileges, filesystem access, and network, exactly as if you'd typed it yourself. Approval is the only boundary; review every command before approving it, the same way you'd review a diff. --command-timeout (default 120s) kills a hung command; stdout and stderr are each capped at 32,000 characters before being shown back to the model.

Current boundaries

This release can apply approved replacements and, opt-in, run approved shell commands (--allow-commands) — but that opt-in is not a sandbox, so read the section above before turning it on. It does not connect to the Forgefy admin catalogue. Provider profiles and skill files are the initial plugin interfaces, not a full autonomous coding-agent system. Output is untrusted: inspect it before running anything, whether it's a file diff or a command result. Tests use mocked HTTP (and, for the process-level suite, a real loopback server), not live model quality benchmarks.

Tests

pytest

Releasing (maintainers)

CI runs on every push/PR (.github/workflows/ci.yml). One tag produces both distribution channels:

1. Bump version in pyproject.toml and commit.
2. git tag vX.Y.Z && git push origin vX.Y.Z.
3. .github/workflows/release.yml then, in parallel:
   • builds and publishes the PyPI package via Trusted Publishing — no token stored in the repo. One-time setup: on the PyPI project's Publishing settings, add a Trusted Publisher for Polybamz/forgefy-cli, workflow release.yml, environment pypi.
   • builds a standalone forgefy binary for Windows/macOS/Linux with PyInstaller and attaches them to a GitHub Release for the tag — what install.sh/install.ps1 fetch. No setup needed; uses the repo's built-in GITHUB_TOKEN.

To build the standalone binary locally (e.g. to test before tagging):

pip install -e . pyinstaller
pyinstaller --onefile --name forgefy --paths src --hidden-import anyio._backends._asyncio --distpath dist_native --workpath build_native --specpath build_native build_installer/entrypoint.py
.\dist_native\forgefy.exe --help