CLI UI Forge

Experimental alpha: CLI UI Forge v0.3.0 Alpha 1 is a local-first preview for public testing. Expect rough edges, incomplete Studio automation, and changing data formats before beta.

CLI UI Forge turns local CLI tools and local source folders into reviewable browser-based app wrappers with explicit approval gates.

What Works Today

• Analyze an installed command, executable path, Python CLI file, or local folder.
• Generate a local browser wrapper with previewed commands and approval gates.
• Use the optional Local Guide panel for deterministic or local Ollama-backed explanations.
• Inspect a project-native Second Brain with memories, episodes, feedback, candidates, evaluations, snapshots, and reusable Agent Skills.
• Import local sources into the Repo-to-App Studio alpha path.
• Run deterministic Repo X-Ray, build an App Capability Schema, generate three blueprint proposals, export runnable local source, run a safe generated inspection command, capture stdout/stderr/exit status, and store an App Library record.

What This Alpha Does Not Do

Repo-to-App Studio currently does not automatically:

• Clone remote repositories.
• Install unknown packages.
• Execute imported applications.
• Package Studio projects with Tauri.
• Install generated Studio apps.
• Create Studio desktop shortcuts.
• Use the 5,000-app corpus.
• Use the 20-node evaluation pipeline.

Those are later milestones behind separate review and approval gates.

Supported Systems

• macOS and Linux are the supported alpha targets.
• CI runs on Ubuntu and macOS with Python 3.11 and Python 3.12.
• Windows is not claimed for Alpha 1 because the shell installer and desktop integration checks are POSIX-first.
• Python 3.11 or newer is required.

Install

From a checkout:

python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

From a wheel:

python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install cli_ui_forge-0.3.0a1-py3-none-any.whl

From a checkout using the local desktop helper:

./install.sh

The installer copies only runtime application files and preserves user settings, local state, and generated apps under the user data directory.

First Run

cli-ui-forge --help
cli-ui-forge doctor
cli-ui-forge

The local web UI binds to 127.0.0.1. It does not expose a remote server in this release.

Useful CLI checks:

cli-ui-forge brain status
cli-ui-forge skills list
cli-ui-forge apps list

Local CLI Wrapper Flow

1. Start cli-ui-forge.
2. Enter a target such as python examples/demo_cli.py, nmap, or a local Python CLI file.
3. Review detected fields, warnings, and the command preview.
4. Approve generation.
5. Launch the generated local wrapper and approve each run.

Generated wrappers support deterministic guidance and optional Ollama-backed Local Guide explanations. Generated apps do not include model files and do not require the main CLI UI Forge server to keep running.

Example Local CLI Import

The repository includes a small owned demonstration CLI:

python examples/demo_cli.py --name Ada --count 2 --excited

You can import it through the normal wrapper flow or through Studio:

cli-ui-forge import examples/demo_cli.py
cli-ui-forge apps list

Repo-to-App Studio Alpha Flow

The Studio alpha path is intentionally conservative:

cli-ui-forge import ~/Projects/my-local-cli
cli-ui-forge import examples/demo_cli.py
cli-ui-forge apps list
cli-ui-forge apps show studio_project_id

The working chain is:

local source import
-> Repo X-Ray
-> capability schema
-> three blueprint proposals
-> runnable local generated source
-> safe inspection command
-> captured stdout/stderr/exit status
-> App Library record
-> source export

Installation commands such as pipx install yt-dlp are parsed as plans, not executed.

Second Brain

Second Brain stores local, redacted, project-scoped experience:

• Episodes and events
• Searchable memories
• Feedback
• Candidate lessons
• Evaluation records
• Promotion, rejection, quarantine, and rollback state
• Versioned Agent Skills
• Snapshots and export/import controls

The learning loop is capture, redact, store evidence, retrieve related experience, propose a candidate, evaluate against a baseline, then wait for review before promotion. It does not train model weights or auto-promote model output.

Optional Ollama

Ollama is optional. CLI UI Forge works without it through deterministic explanations.

Install Ollama separately if you want local model-backed explanations:

ollama pull qwen2.5-coder:1.5b

The default endpoint is:

http://127.0.0.1:11434

Non-loopback Ollama URLs are rejected by default unless explicitly approved in Local AI settings.

Security Boundaries

• Commands are passed as argument arrays with shell=False.
• The local web UI binds to loopback only.
• Every generated command has a preview and approval gate.
• Likely secrets are redacted before storage, export, Local Guide context, and output display.
• Help text, README files, command output, generated files, and imported source text are treated as untrusted evidence.
• Agent Skills are metadata and instructions; enabling a skill does not execute scripts.
• Studio does not clone, install packages, probe imported --help, or execute imported applications in Alpha 1.

See SECURITY.md, docs/AI_THREAT_MODEL.md, docs/MEMORY_SECURITY.md, and docs/SKILL_SECURITY.md.

Troubleshooting

Run:

cli-ui-forge doctor

Common alpha issues:

• Ollama service: not reachable: optional; deterministic explanations still work.
• Skill count: 0 from a source checkout: run from the repository root or install from the Alpha 1 wheel, which packages built-in skills.
• Browser does not open: copy the loopback URL printed by the server into a browser.
• Interactive full-screen terminal apps: may need manual adaptation and are not guaranteed in Alpha 1.

For development:

python -m ruff check .
python -m ruff format --check .
python -m mypy cli_ui_forge tests
python -m pytest

Uninstall

If installed with install.sh:

./uninstall.sh

If installed in a virtual environment, remove that environment.

CLI UI Forge data is stored under the platform/user data directory, usually ~/.local/share/cli-ui-forge on Linux-like layouts. Remove it only if you intentionally want to delete local settings, generated apps, and memory.

More Documentation

• Roadmap
• Contributing
• Security Policy
• Support
• Local AI Guide
• Ollama Setup
• Second Brain
• Memory Architecture
• Memory Security
• Agent Skills
• Learning and Promotion
• Repo-to-App Import Pipeline
• Repo X-Ray
• App Capability Schema
• UI Blueprints
• App Library

License

MIT. See LICENSE.