CLI Development Server & Session Metadata
Developer Live-Reload Sync
Aircada CLI provides a real-time development mode (air dev) that establishes a localized WebSocket and HTTP/HTTPS server.
This mounts a high-performance, live-sync channel directly connecting your local filesystem with the active web-based AIRCADA STUDIO Panel viewport.
Dev Session Runtime Metadata (.aircada/dev-session.json)
When air dev launches, the CLI automatically writes real-time runtime metadata to <projectRoot>/.aircada/dev-session.json:
{
"pid": 17492,
"devPort": 9005,
"projectRoot": "C:\\path\\to\\project",
"projectId": "SwVpawyqDK1qpDKw",
"name": "basic",
"mode": "ui",
"studioUrl": "https://localhost:3002/SwVpawyqDK1qpDKw?devPort=9005&mode=ui",
"startedAt": "2026-09-15T17:08:40.483Z"
}Automated tools, test scripts, and browser testing subagents inspect this file to obtain the exact studioUrl without trial-and-error port scanning or protocol guessing.
CLI Dev Server Hot-Swapping & Telemetry Architecture#
Dev-Client WebSocket Bridge & State Preservation
Alongside code-update and build-error frames on Port 9005, the dev-client WebSocket bridge forwards live browser console and runtime telemetry back to the CLI terminal. During hot-swaps, AIR Engine snapshots active operator fields into _hot_snapshots_ and restores state after re-instantiation so live configurator selections persist across edits without a full page reload.
Dual-Channel Communication Architecture
During live development sessions (air dev), the CLI dev server coordinates files, bundles, and remote APEX instructions across a WebSocket (Port 9005), HTTP server, and REST API mutations pipeline:
graph TD
subgraph Local Workspace
A[File Watcher: Chokidar] -->|Detects Change| B[Builder: Scan + Gen virtual entry]
B -->|Compile Bundle| C[Bundler: esbuild]
C -->|Raw JS Code| D[Dev Server]
end
subgraph Dual Communication Channel
D -->|WS: code-update / build-error| E(WebSocket Server - Port 9005)
D -->|HTTP: GET /bundle.js| F(HTTP Server - Port 9005)
D -->|HTTP: POST /api/apex/execute| G(REST APEX endpoint)
end
subgraph Aircada Studio - Live Web App
E <-->|WS Link| H[Studio Runtime Engine]
H -->|Hot Swap Bundle| I[Interactive Preview]
H -.->|Trigger remote mutation| G
end
classDef local fill:#2a2b36,stroke:#4a50ff,stroke-width:2px,color:#fff;
classDef comm fill:#1c1d24,stroke:#39c362,stroke-width:2px,color:#fff;
classDef cloud fill:#202127,stroke:#e95420,stroke-width:2px,color:#fff;
class A,B,C,D local;
class E,F,G comm;
class H,I cloud;Step-by-Step Hot Swap Loop
- File Watcher (Chokidar): Monitors your local
src/folder for TypeScript edits.
- Incremental Builder (esbuild): Re-compiles your bundle into an optimized virtual distribution output in milliseconds upon change.
- Telemetry Push: The Dev Server broadcasts a
code-updateWebSocket frame containing the raw JS bundle to the web dashboard runtime.
- Interactive Swap: The Aircada Studio runtime intercepts the WebSocket event, immediately evaluates the new logic block, and hot-swaps it into the active browser spatial preview without refreshing or losing session state.
- Dynamic Mutations (APEX REST): Interactive gestures or changes in Aircada Studio propagate remote mutation calls back to the REST APEX endpoint, maintaining synchronized local-to-cloud alignment.
Ephemeral Authentication Loopback Flow
Logging into the CLI (air login) coordinates securely with the browser without manual credentials copying via a custom loopback sequence:
sequenceDiagram
autonumber
participant CLI as CLI (air login)
participant OS as OS / Default Browser
participant Cloud as Aircada Live Webapp
participant LocalHost as Ephemeral Local HTTP Server
CLI->>LocalHost: Bind to random port & register state token
CLI->>OS: open(Aircada Studio Auth URL + Port + State)
OS->>Cloud: Navigate to Auth Page
Note over Cloud: User logs in via Web UI
Cloud->>LocalHost: POST /auth-callback (Credentials + State)
LocalHost->>LocalHost: Validate state token
LocalHost-->>CLI: Resolve credentials payload
CLI->>CLI: Encrypt and store locally in credentials.lock
LocalHost->>Cloud: Response: Status 200 OK
CLI->>LocalHost: Graceful shutdown & terminate server