aiel-cli

aiel — AI Execution Layer 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:

---

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

┌────────────────────┐
│ 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

---

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:

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

pip install aiel-cli

Requirements:

• Python 3.10+
• Access token for the Execution Plane

---

Quick Start

1. Authenticate

aiel auth login

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

---

2. Configure Workspace Context

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

aiel init

This creates local execution metadata under .aiel/.

Example:

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

---

4. Pull Remote Snapshot State

aiel pull

Downloads the active remote snapshot into the local working tree.

---

5. Stage and Commit Changes

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

Commits are local metadata operations until pushed.

---

6. Deploy to the Execution Plane

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

aiel auth login

Validates the token through:

GET /v1/auth/me

---

Status

aiel auth status

Returns non-zero when credentials are invalid or missing.

Useful for CI validation.

---

Profiles

aiel auth list

Supports multiple environments and profiles.

---

Logout

aiel auth logout --profile production

Removes locally stored credentials.

---

Credential Resolution

Resolution order:

1. AIEL_TOKEN
2. OS keyring
3. Credentials file

Credential storage:

---

Workspace Configuration

List Current Context

aiel config list

Displays:

• active profile
• workspace
• project
• base URL

---

Set Workspace

aiel config set workspace payments

The CLI validates visibility against the authenticated identity.

---

Set Project

aiel config set project fraud_detection

Projects define deployment scope inside a workspace.

---

Repository Synchronization

Repository state is managed under .aiel/.

Initialize Repository

aiel init

Creates local metadata and bootstrap files.

---

View Status

aiel status

Displays:

• staged changes
• unstaged changes
• manifest drift
• pending commits

---

Stage Files

aiel add .

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

---

Commit

aiel commit -m "Update routing policy"

Creates local commit metadata.

---

Pull Snapshot

aiel pull

Hydrates the local tree from the active remote snapshot.

---

Push Snapshot

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

aiel integrations list

---

Validate Integration Health

aiel integrations check --provider postgres

---

Introspection & Operational Visibility

Active Execution Context

aiel info workspace

Displays:

• tenant
• workspace
• project
• authenticated identity

---

Visible Workspaces

aiel info workspaces

---

Visible Projects

aiel info projects

---

Manifest Inspection

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:

pip install -e .[dev]

Run tests:

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.