Metadata-Version: 2.4
Name: forgefy-cli
Version: 0.3.0
Summary: Forgefy CLI — coding assistance with local and hosted model-provider profiles.
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://forgefy.app
Project-URL: Repository, https://github.com/Polybamz/forgefy-cli
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# 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:
```sh
curl -fsSL https://raw.githubusercontent.com/Polybamz/forgefy-cli/main/install.sh | sh
```

Windows (PowerShell):
```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:

```powershell
pipx install forgefy-cli
```

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

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

### Developing locally

```powershell
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:

```powershell
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.

```powershell
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:

```toml
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

```powershell
& '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:

```powershell
& '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

```powershell
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):

```powershell
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
```

