Metadata-Version: 2.4
Name: aiel-cli
Version: 1.3.9
Summary: AI Execution Layer CLI
Author-email: Aldenir Flauzino <aldenirsrv@gmail.com>
License: 
        ```text
        MIT License
        
        Copyright (c) 2025 <Aldenir Flauzino>
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        ```
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7
Requires-Dist: questionary>=2.0.0
Requires-Dist: rich>=13.7.1
Requires-Dist: typer>=0.12.3
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Description-Content-Type: text/markdown

# aiel — AI Execution Layer CLI

![PyPI](https://img.shields.io/pypi/v/aiel-cli)

`aiel` is the command-line interface for the AI Execution Layer: a managed execution platform for deploying, governing, and operating AI workflows in production.

The platform separates AI application development from execution infrastructure.

Instead of building:
- orchestration runtimes
- execution gateways
- policy middleware
- deployment infrastructure
- audit pipelines
- integration control layers

teams define workflows locally and push immutable execution snapshots into the Execution Plane.

The platform becomes responsible for:
- runtime provisioning
- policy enforcement
- integration governance
- execution routing
- observability
- auditability
- execution isolation
- versioned deployments

---

# Why AIEL Exists

Most AI projects do not fail during prompting.

They fail when organizations try to operationalize AI systems safely across real infrastructure.

Production AI execution introduces problems that prototypes never solve:
- uncontrolled tool access
- inconsistent runtime environments
- duplicated orchestration logic
- missing audit trails
- unsafe integrations
- non-reproducible deployments
- environment drift
- ungoverned execution

The AI Execution Layer standardizes this operational layer through a governed execution plane.

Teams focus on workflow logic.

The platform handles execution infrastructure.

---

# System Architecture

The AI Execution Layer consists of four primary components:

| Component | Responsibility |
|---|---|
| `aiel-sdk` | Local development contract and execution abstractions |
| `aiel-cli` | Packaging, validation, versioning, and deployment interface |
| `aiel-runtime` | Remote execution adapter used inside the Execution Plane |
| Execution Plane | Managed runtime system responsible for governed execution |

---

# Execution Model

The platform uses immutable execution snapshots.

Every deployment creates a versioned snapshot containing:
- workflow definitions
- execution metadata
- dependency manifests
- capability contracts
- integration references
- runtime configuration

Snapshots are validated before becoming executable.

The Execution Plane then loads the snapshot into a governed runtime environment.

---

# Architecture Flow

```text
┌────────────────────┐
│ Local AI Project   │
└─────────┬──────────┘
          │
          │ aiel push
          ▼
┌────────────────────┐
│ Snapshot Packaging │
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│ Contract Validation│
└─────────┬──────────┘
          │
          ▼
┌──────────────────────────┐
│ Immutable Snapshot Store │
└─────────┬────────────────┘
          │
          ▼
┌──────────────────────────┐
│ AI Execution Plane       │
├──────────────────────────┤
│ Runtime Hydration        │
│ Policy Enforcement       │
│ Capability Registry      │
│ Integration Governance   │
│ Execution Routing        │
│ Observability Pipeline   │
│ Audit Logging            │
└─────────┬────────────────┘
          │
          ▼
┌──────────────────────────┐
│ Workflow / Tool Runtime  │
└──────────────────────────┘
```

---

# Local vs Remote Responsibilities

| Local Development | Execution Plane |
|---|---|
| Author workflows | Execute workflows |
| Define tools/agents | Provision runtimes |
| Package snapshots | Enforce policies |
| Stage local changes | Route execution |
| Test locally | Generate audit logs |
| Configure workspace context | Govern integration access |

---

# Execution Guarantees

The platform is designed around deterministic and governed execution.

## Immutable Snapshots
Every deployment is versioned and immutable.

## Reproducible Runtime Environments
Execution environments are hydrated from validated runtime metadata.

## Policy Enforcement
Policies are evaluated before execution occurs.

## Integration Governance
External systems are exposed through scoped capabilities.

## Full Traceability
Execution metadata, actions, and runtime events are auditable.

## Workspace Isolation
Execution contexts remain isolated per workspace and project.

## Versioned Deployments
Deployments can be inspected, versioned, and rolled back safely.

---

# Runtime Architecture

`aiel-runtime` is the execution adapter used by the Execution Plane.

The runtime is responsible for:
- loading execution snapshots
- hydrating runtime environments
- registering capabilities
- resolving integrations
- enforcing execution contracts
- routing tool execution
- collecting telemetry
- returning normalized execution responses

The runtime standardizes execution behavior across:
- agents
- workflows
- tools
- routers
- orchestration frameworks

---

# SDK Architecture

`aiel-sdk` provides the local development contract for AI applications.

The SDK exposes:
- typed execution interfaces
- workflow decorators
- integration abstractions
- execution contracts
- local validation
- framework adapters

The SDK mirrors the production execution surface so local development remains consistent with remote runtime behavior.

Example:

```python
from aiel import tool, agent

@tool
def search_orders(order_id: str):
    ...

@agent
def support_agent():
    ...
```

The SDK itself does not execute workflows in production.

Execution occurs remotely inside the Execution Plane through `aiel-runtime`.

---

# CLI Responsibilities

The CLI is the deployment and operational interface into the platform.

Primary responsibilities:
- authentication
- workspace selection
- snapshot packaging
- contract validation
- manifest synchronization
- deployment operations
- runtime introspection
- execution metadata inspection

The CLI intentionally abstracts infrastructure management from application teams.

---

# Installation

```bash
pip install aiel-cli
```

Requirements:
- Python 3.10+
- Access token for the Execution Plane

---

# Quick Start

## 1. Authenticate

```bash
aiel auth login
```

The CLI validates credentials against the control plane and stores the active profile securely.

---

## 2. Configure Workspace Context

```bash
aiel config set workspace <workspace-slug>
aiel config set project <project-slug>
```

Workspace and project scope determine:
- deployment isolation
- integration visibility
- policy scope
- runtime permissions

---

## 3. Initialize a Project

```bash
aiel init
```

This creates local execution metadata under `.aiel/`.

Example:

```text
.aiel/
├── state.json
├── index.json
├── commits/
└── .aielignore
```

---

## 4. Pull Remote Snapshot State

```bash
aiel pull
```

Downloads the active remote snapshot into the local working tree.

---

## 5. Stage and Commit Changes

```bash
aiel status
aiel add .
aiel commit -m "Add customer support workflow"
```

Commits are local metadata operations until pushed.

---

## 6. Deploy to the Execution Plane

```bash
aiel push
```

`aiel push` performs the following operations:

1. Packages the current project
2. Computes content hashes
3. Validates execution contracts
4. Builds snapshot metadata
5. Uploads immutable artifacts
6. Registers a versioned snapshot
7. Refreshes manifest state
8. Publishes the snapshot to the Execution Plane

The Execution Plane then becomes responsible for:
- runtime provisioning
- policy enforcement
- integration access
- execution routing
- telemetry
- auditability

No container orchestration configuration is required.

No custom runtime infrastructure is required.

No deployment pipeline configuration is required.

---

# Authentication

## Login

```bash
aiel auth login
```

Validates the token through:

```text
GET /v1/auth/me
```

---

## Status

```bash
aiel auth status
```

Returns non-zero when credentials are invalid or missing.

Useful for CI validation.

---

## Profiles

```bash
aiel auth list
```

Supports multiple environments and profiles.

---

## Logout

```bash
aiel auth logout --profile production
```

Removes locally stored credentials.

---

# Credential Resolution

Resolution order:

1. `AIEL_TOKEN`
2. OS keyring
3. Credentials file

Credential storage:

| Platform | Location |
|---|---|
| macOS/Linux | `~/.config/aiel/credentials.json` |
| Windows | `%APPDATA%/aiel/credentials.json` |

---

# Workspace Configuration

## List Current Context

```bash
aiel config list
```

Displays:
- active profile
- workspace
- project
- base URL

---

## Set Workspace

```bash
aiel config set workspace payments
```

The CLI validates visibility against the authenticated identity.

---

## Set Project

```bash
aiel config set project fraud_detection
```

Projects define deployment scope inside a workspace.

---

# Repository Synchronization

Repository state is managed under `.aiel/`.

## Initialize Repository

```bash
aiel init
```

Creates local metadata and bootstrap files.

---

## View Status

```bash
aiel status
```

Displays:
- staged changes
- unstaged changes
- manifest drift
- pending commits

---

## Stage Files

```bash
aiel add .
```

Stages upserts and deletions into `.aiel/index.json`.

---

## Commit

```bash
aiel commit -m "Update routing policy"
```

Creates local commit metadata.

---

## Pull Snapshot

```bash
aiel pull
```

Hydrates the local tree from the active remote snapshot.

---

## Push Snapshot

```bash
aiel push
```

Publishes a new immutable snapshot into the Execution Plane.

---

# Integration Governance

Integrations are managed as governed execution capabilities.

The platform standardizes:
- integration registration
- connection validation
- capability exposure
- policy attachment
- scoped access

---

## List Integrations

```bash
aiel integrations list
```

---

## Validate Integration Health

```bash
aiel integrations check --provider postgres
```

---

# Introspection & Operational Visibility

## Active Execution Context

```bash
aiel info workspace
```

Displays:
- tenant
- workspace
- project
- authenticated identity

---

## Visible Workspaces

```bash
aiel info workspaces
```

---

## Visible Projects

```bash
aiel info projects
```

---

## Manifest Inspection

```bash
aiel files ls
```

Displays:
- current manifest tree
- snapshot metadata
- local execution state

---

# Ignore Rules

`.aielignore` controls:
- synchronization
- staging
- status calculation
- deployment packaging

Behavior is similar to `.gitignore`.

---

# Operational Model

The platform is designed around explicit operational boundaries.

## Control Plane
Responsible for:
- authentication
- workspace management
- snapshot registry
- deployment metadata
- policy configuration

## Execution Plane
Responsible for:
- runtime hydration
- workflow execution
- integration access
- execution isolation
- observability
- telemetry
- auditability

---

# Testing

Install development dependencies:

```bash
pip install -e .[dev]
```

Run tests:

```bash
pytest --cov=aiel --cov-report=term-missing
```

The test suite validates:
- CLI behavior
- snapshot workflows
- manifest synchronization
- contract validation
- execution metadata handling
- repository state transitions

---

# Roadmap

The platform roadmap includes:
- execution logs
- deployment rollback
- runtime debugging
- environment promotion
- policy simulation
- execution replay
- approval gates
- canary deployments
- multi-runtime execution support

---

# Contributing

1. Fork the repository
2. Create a Python 3.10+ virtual environment
3. Install development dependencies
4. Run tests before opening a PR
5. Update documentation when exposing new execution behavior

---

# Philosophy

AI systems become operationally complex when they interact with real infrastructure.

The AI Execution Layer exists to standardize:
- execution
- governance
- integrations
- runtime behavior
- operational safety

so teams can ship production AI systems without rebuilding the same infrastructure repeatedly.
