ECLI

Terminal-First Engineering Operations Workbench
Panel-driven editor, diagnostics surface, and service foundation for controlled operational workflows

---

🚀 About ECLI

ECLI (Editor CLI) is a terminal-first engineering operations workbench. It combines a curses-based editor with right-side workflow panels and a typed service foundation for configuration, project discovery, command-plan previews,policy checks, audit logging, privileged-action refusal paths, and read-only system diagnostics.

The v0.2.1 release keeps the Services Foundation editor surface intact and hardens release packaging, source-text preservation, and cross-platform install paths. It does not execute remediation, apply command plans, launch VMLab runtimes, or perform real privileged operations.

✨ Key Features

• 🧠 AI Code Assistant - F7 panel for code-generation and refactoring help when a user-provided API key is configured

• 🩺 System Doctor - F8 read-only diagnostics panel with structured findings and preview-only remediation plans

• 🧭 Services Panel - right-side visibility into the Phase 1 service composition root

• 📋 Command Plan Preview - draft plans from eligible diagnostics, exportable as JSON or Markdown without execution

• 📂 File Manager - F10 project navigation and file preview workflow

• 🌱 Git Panel - F9 repository panel for existing Git workflows

• 🔎 Diagnostics/Lint - F4 diagnostics and lint panel

• ❓ Help - F1 help panel with current keybindings

• 🌈 Syntax Highlighting - terminal highlighting for common source formats

• 📝 LSP Integration - Language Server Protocol support where configured

• 🔄 Cross-Platform Packaging - PyPI, Linux, FreeBSD, macOS, and Windows release artifacts

---

📥 Quick Start

Fastest Installation (Pre-built Packages)

Download and install a pre-compiled package for your platform when available:

# Debian/Ubuntu
sudo apt install ./ecli_<version>_linux_x86_64.deb

# Fedora/RHEL/Rocky/Alma
sudo dnf install ./ecli_<version>_linux_x86_64.rpm

# SUSE/openSUSE
sudo zypper install ./ecli_<version>_opensuse_x86_64.rpm

# Arch Linux
sudo pacman -U ./ecli_<version>_arch_x86_64.pkg.tar.zst

# Slackware
sudo installpkg ecli_<version>_slackware_x86_64.txz

# NixOS / Nix
nix run .

# AppImage
chmod +x ./ecli_<version>_linux_x86_64.AppImage
./ecli_<version>_linux_x86_64.AppImage

# Windows (PowerShell)
.\ecli_<version>_win_x86_64_setup.exe
# Portable alternative: .\ecli_<version>_win_x86_64.exe
# See docs/install/windows.md for checksum verification and SmartScreen notes.

# macOS
open ecli_<version>_macos_universal2.dmg
# First launch is blocked by Gatekeeper; see docs/install/macos.md
# for the one-time "Open Anyway" or xattr workaround.

Release artifacts are published at GitHub Releases when available.

Run from Source

# Clone the repository
git clone https://github.com/SSobol77/ecli.git
cd ecli

# Install dependencies and run
make install
make run

Install from PyPI

sudo apt update
sudo apt install pipx
pipx ensurepath
pipx install ecli-editor
ecli

The Python distribution name is ecli-editor; the import package remains ecli, and the installed CLI command remains ecli.

Optional Linux desktop launcher and icon integration after pipx or pip installation:

ecli-install-desktop-entry

This installs a user-level launcher at ~/.local/share/applications/ecli.desktop and the icon at ~/.local/share/icons/hicolor/256x256/apps/ecli.png. It does not require sudo and is safe to run again.

---

📦 Installation Guide

Complete Installation Instructions

For detailed platform-specific installation instructions, system dependencies, and troubleshooting, see the Installation Guide.

1. System Dependencies

These dependencies are required for terminal UI, clipboard integration, YAML acceleration, and UTF-8 support.

Debian/Ubuntu:

sudo apt update && sudo apt install \
  libncurses6 libncursesw6 libtinfo6 \
  libncurses-dev libncursesw5-dev \
  ncurses-bin ncurses-term \
  libyaml-dev xclip xsel

Fedora/RHEL/Rocky/Alma:

sudo dnf install ncurses ncurses-devel libyaml-devel xclip xsel

SUSE/openSUSE runtime:

sudo zypper install ncurses6 libyaml-0-2 xclip xsel

For local RPM/package builds on SUSE/openSUSE:

sudo zypper install python3 python3-pip python3-devel gcc make rpm-build

Arch Linux:

sudo pacman -S ncurses libyaml xclip xsel

Slackware:

Install these from the official Slackware series or SlackBuilds according to your Slackware release:

ncurses
libyaml
xclip or xsel, if available

For .txz package builds, the build host also needs makepkg, tar, xz, python3, PyInstaller, and the project Python build dependencies.

FreeBSD:

sudo pkg install ncurses libyaml xclip xsel

macOS:

brew install ncurses libyaml

Windows:

Prebuilt installer and portable .exe artifacts do not require a separate Python installation. Windows Terminal or another modern terminal is recommended, PowerShell is used for checksum examples, and Git is optional for repository workflows. The official installer normally bundles the required runtime components; install the Visual C++ runtime only if a release note says that a specific artifact requires it.

For source/development builds on Windows, install Python 3.11+, Git, PowerShell 7, NSIS for installer builds, and Visual Studio Build Tools only when native dependency or build-tool compilation is required.

2. Install ECLI

Option A: Pre-built Packages (Recommended)

Download from GitHub Releases when available:

• Linux: .deb (Debian/Ubuntu), .rpm (Fedora/RHEL and SUSE/openSUSE), Arch pkg.tar.zst, Slackware .txz, AppImage

• FreeBSD: .pkg

• macOS: .dmg (install notes)

• Windows: .exe installer or portable executable (install notes)

• Release metadata: CycloneDX SBOM and SHA256 sidecars for release artifacts

Option B: PyPI (Python Package Index)

sudo apt update
sudo apt install pipx
pipx ensurepath
pipx install ecli-editor
ecli

Import and launch names are unchanged:

import ecli

ecli

For isolated development or testing:

python3 -m venv ~/.local/ecli-env
source ~/.local/ecli-env/bin/activate
pip install ecli-editor
ecli

On Debian 13 and newer Ubuntu releases, direct system-level pip install may fail with externally-managed-environment. Use pipx, a virtual environment, or the official .deb package from GitHub Releases when available.

Avoid pip install --break-system-packages ecli-editor unless you fully understand the apt package-management consequences.

Requires Python 3.11+ and system dependencies listed above. Native packages may install launcher integration automatically; pip/pipx installs use ecli-install-desktop-entry for explicit Linux desktop integration.

Linux Package Commands

Use release artifacts from GitHub Releases when available. Exact artifact names include version and architecture.

# Debian / Ubuntu
sudo apt install ./ecli_<version>_linux_x86_64.deb

# Fedora / RHEL
sudo dnf install ./ecli_<version>_linux_x86_64.rpm

# SUSE / openSUSE
sudo zypper install ./ecli_<version>_opensuse_x86_64.rpm

# Arch Linux release artifact
sudo pacman -U ./ecli_<version>_arch_x86_64.pkg.tar.zst

# Arch Linux local PKGBUILD
cd packaging/arch
makepkg -si

# Slackware
sudo installpkg ecli_<version>_slackware_x86_64.txz
sudo upgradepkg ecli_<version>_slackware_x86_64.txz
sudo removepkg ecli

# NixOS / Nix
nix run .
nix build .
nix profile install .

# FreeBSD
sudo pkg add ./ecli_<version>_freebsd_x86_64.pkg

# AppImage
chmod +x ./ecli_<version>_linux_x86_64.AppImage
./ecli_<version>_linux_x86_64.AppImage

The Arch package is named ecli-editor and installs the ecli command. Raw makepkg output may use ecli-editor-<version>-1-<arch>.pkg.tar.zst;

the ECLI release script normalizes it to ecli_<version>_arch_<arch>.pkg.tar.zst for GitHub Releases. AUR publishing is not implemented by this repository yet. If openSUSE dependencies are missing, use zypper to resolve them from configured repositories.

---

🔨 Building from Source

Prerequisites

• Python 3.11+

• Git

• System dependencies (see above)

• uv package manager (optional, for faster builds)

Build Steps

# Clone the repository
git clone https://github.com/SSobol77/ecli.git
cd ecli

# Install dependencies
make install

# Run from source
make run

# Build packages for distribution
make help              # See all available build targets

Build System

ECLI features a comprehensive multi-platform build system. For detailed information:

• Build from Source: Read docs/contributor/build-from-source.md

• Packaging Flows: See docs/release/packaging-flows.md

Common Build Commands

# Display all available build targets
make help

# Check system capabilities and available tools
make sysinfo

# Build for your platform
make package-linux      # Linux package targets supported by the local toolchain
make package-pypi       # Python wheel + source distribution
make package-macos      # macOS DMG
make package-windows    # Windows portable EXE + installer
make package-freebsd    # FreeBSD package

# Release to GitHub (requires GitHub CLI)
make publish-all

---

🚀 Usage

Launch ECLI

ecli [options] [file]

Keyboard Shortcuts

Master ECLI with these essential keyboard shortcuts. Press F1 anytime inside the editor to open the help screen.

Basic Editing

Shortcut	Action
Backspace	Delete character left / delete selection
Tab	Smart indent / indent block
Shift+Tab	Smart unindent
Ctrl+\	Toggle comment (line/block)
Ctrl+C	Copy
Ctrl+X	Cut
Ctrl+V	Paste
Ctrl+A	Select all
Ctrl+Z	Undo
Ctrl+Y	Redo

Navigation & Search

Shortcut	Action
Ctrl+G	Go to line
Ctrl+F	Find
F3	Find next
F6	Search & Replace with regex support
Arrow keys / Home / End	Cursor movement
Page Up / Page Down	Scroll by page
Shift + Arrow keys	Extend selection

File Operations

Shortcut	Action
F2	New file
Ctrl+O	Open file
Ctrl+S	Save
F5	Save as...
Ctrl+Q	Quit editor

Tools & Panels

Shortcut	Action
F10	File Explorer
F4	Diagnostics / Linter panel
F9	Git menu
F7	AI Assistant panel
F8	System Doctor
F1	Show Keyboard Shortcuts
Esc	Close current panel
Insert	Toggle Insert / Overwrite mode
F12	Switch focus between editor windows and panels

The right side of the editor hosts workflow panels. The v0.2.1 service panels are read-only or preview-only: System Doctor does not mutate host state, Command Plan previews do not execute, and the Services panel reports composition status.

Minimal Service CLI

The default CLI path still launches the editor:

python3 -m ecli
python3 -m ecli pyproject.toml

The explicit service flags provide read-only inspection without bypassing the TUI model:

python3 -m ecli --services
python3 -m ecli --doctor
python3 -m ecli --plan-preview

Use --json for deterministic JSON output where supported. These commands are inspection and preview surfaces only; they do not execute plans, run privileged commands, install packages, start VMLab, or apply remediation.

AI Configuration

AI features require user-provided provider credentials. API keys belong in:

~/.config/ecli/.env

Provider selection belongs in config.toml, not in .env. If a selected provider key is missing, the AI panel reports a normal configuration message instead of a Python traceback.

For comprehensive keybindings and usage guide, see Getting Started.

---

📚 Documentation

Complete documentation is organized by audience:

For Users

• Installation Guide - Detailed setup instructions

• Build from Source - Build system quick start

• Getting Started - First steps with ECLI

For Developers

• Development Setup - Development environment

• Architecture Overview - System design

• Packaging Flows - Release packaging overview

• Build from Source - Local build commands

• Contributor Guide - Contributing to ECLI

For System Administrators

• Supported Platforms - Platform matrix

• Configuration Guide - Configuration options

• Deployment Guide - Production deployment

Reference

• API Documentation - Plugin development

• Architecture Details - System internals

• Release Process - Release management

• Quality Standards - Testing and quality gates

---

🏗️ Architecture

ECLI v0.2.1 keeps the existing editor/TUI behavior and introduces the Services Foundation as typed, testable service-layer infrastructure:

• Core Editor: curses-based terminal editor with async task integration

• Right-Side Panels: Help, Diagnostics/Lint, AI Code Assistant, System Doctor, Git, File Manager, Services, and Command Plan previews

• ConfigService: typed layered configuration loading

• ProjectService: deterministic project discovery and path normalization

• CommandPlanService: draft command-plan models and preview/export behavior

• BuiltInPolicyEngine: deterministic built-in policy evaluation rules

• AuditLogService: append-only JSONL audit records with mandatory redaction

• PrivilegedActionService: refusal-only/dry-run-only skeleton for future elevated operations

• SystemDoctor: read-only diagnostic skeleton with draft remediation-plan generation

• ServiceRegistry: explicit composition root without global service-locator state

Safety boundaries for v0.2.1:

• SystemDoctor is read-only.

• CommandPlan output is draft/preview-only.

• PrivilegedActionService refuses real execution in this release.

• Service panels are visible in the UI but do not execute remediation.

• VMLab runtime behavior is not included in v0.2.1.

For detailed architecture information, see Architecture Overview.

---

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository

2. Clone your fork: git clone https://github.com/YOUR_USERNAME/ecli.git

3. Create a feature branch: git checkout -b feature/your-feature

4. Make your changes

5. Test your changes: make clean && make install && make run

6. Commit with clear messages

7. Push to your fork

8. Open a Pull Request

For detailed contribution guidelines, see CONTRIBUTING.

---

⚙️ Development

Setting Up Development Environment

# Clone and setup
git clone https://github.com/SSobol77/ecli.git
cd ecli

# Install dev dependencies
make install

# Run tests
python -m pytest

# Run linter
ruff check src/

# Format code
black src/

Project Structure

ecli/
├── src/ecli/              # Main source code
│   ├── core/              # Core editor functionality
│   ├── ui/                # Terminal UI components
│   ├── integrations/      # AI, Git, LSP integrations
│   └── utils/             # Utilities and helpers
├── docs/                  # Documentation
├── tests/                 # Test suite
├── scripts/               # Build and utility scripts
└── Makefile               # Multi-platform build system

---

🐛 Issues & Bug Reports

Found a bug? Please help us by opening an issue on GitHub:

• Issue Tracker

• Include: OS, Python version, ECLI version, and reproduction steps

• Check Known Issues first

---

📋 Requirements

Minimum Requirements

• OS: Linux, macOS, FreeBSD, or Windows

• Python: 3.11 or higher

• Terminal: Supports 256 colors and UTF-8

Supported Platforms

• Ubuntu 20.04 LTS and newer

• Debian 11 and newer

• Fedora 36 and newer

• RHEL/CentOS/Rocky 8.0 and newer

• Arch Linux (current)

• FreeBSD 14.0 and newer

• macOS 12 and newer

• Windows 10/11

See Supported Platforms for detailed compatibility matrix.

---

📝 License

ECLI is licensed under the Apache License 2.0. See the LICENSE file for details.

---

🔗 Links

• Website: https://www.ecli.io

• GitHub: https://github.com/SSobol77/ecli

• Issues: https://github.com/SSobol77/ecli/issues

• Discussions: https://github.com/SSobol77/ecli/discussions

• PyPI: https://pypi.org/project/ecli-editor/

• Releases: https://github.com/SSobol77/ecli/releases

---

💬 Support

• Documentation: Read Build from Source and Packaging Flows

• Community: GitHub Discussions

• Bugs: GitHub Issues

• Development: See Contributing

---

🎯 Roadmap

For planned features and current development status, see Roadmap.

---

Made with ❤️ by the ECLI community
⭐ Star us on GitHub!