Skip to content

deanyou/virtuoso-cli

BranchesTags

Repository files navigation

vcli — Virtuoso CLI

crates.io Rust 1.75+ License: MIT CI

English | 中文

English

Control Cadence Virtuoso from anywhere — locally or remotely. Designed for AI Agents and humans alike.

Based on virtuoso-bridge-lite by Arcadia-1. vcli is a full Rust rewrite and major extension of that project, adding multi-session support, dynamic port assignment, session registry, an agent-native CLI, and Spectre simulation integration.

Overview

vcli is a lightweight Rust-based bridge tool for executing SKILL code outside of Virtuoso. It starts a Rust daemon inside Virtuoso via ramic_bridge.il, which accepts commands over TCP, calls evalstring, and returns results.

Key Features

  • Multi-session support — Multiple Virtuoso instances on the same server each get a unique session ID and random port, with no conflicts
  • Multi-session broadcast — vcli skill broadcast fans out to all live sessions concurrently via scoped threads; subagent mode supports heterogeneous multi-step per-session workflows
  • Dynamic port assignment — Daemon binds port 0 (OS assigns), eliminating port collision
  • Session auto-discovery — Single session connects automatically; multiple sessions require --session or VB_SESSION; stale session files for dead daemons are silently filtered out
  • Session history — Per-session SKILL execution log and CLI command history; survives reconnection (vcli session history <id>)
  • Three programming modes — Raw SKILL expressions, high-level API, or load .il files directly
  • Local + remote modes — Direct local connection or SSH tunnel with ControlMaster multiplexing
  • Agent-native CLI — Noun-verb command structure, JSON structured output, schema introspection, semantic exit codes
  • Schematic editing & reading — Create, place, wire, connect + read instances, nets, pins, parameters
  • Maestro ADE management — Open/close Explorer (maestro) view sessions, set variables, run simulations, export results (IC23.1+ unified ADE)
  • Spectre simulation — Sync/async simulation, job registry with status tracking and atomic file writes, PSF parser
  • Multi-profile support — --profile flag for concurrent connections to multiple Virtuoso instances
  • Command logging — All SKILL executions logged to ~/.cache/virtuoso_bridge/logs/commands.log
  • Interactive TUI — vtui terminal dashboard showing sessions, jobs, tunnel status

Installation

From crates.io (recommended):

cargo install virtuoso-cli                          # vcli (main CLI)
cargo install virtuoso-cli --bin vtui               # vtui (interactive TUI dashboard)
cargo install virtuoso-cli --features daemon        # virtuoso-daemon (bridge backend)

From source:

git clone https://github.com/deanyou/virtuoso-cli.git
cd virtuoso-cli
cargo install --path .

All binaries (vcli, vtui) are installed to ~/.cargo/bin/.

Note: Do not name the binary virtuoso — it conflicts with Cadence's virtuoso executable.

Quick Start

1. Load RAMIC Bridge in Virtuoso CIW:

load("/path/to/virtuoso-cli/resources/ramic_bridge.il")

load automatically stops any existing daemon, resets the path to ~/.cargo/bin/virtuoso-daemon, starts fresh, and prints the Ready banner — works for first load and for reloading after updates.

Output:

┌─────────────────────────────────────────┐
│  vcli (Virtuoso CLI Bridge) — Ready     │
├─────────────────────────────────────────┤
│  Session : eda-meow-1                   │
│  Port    : 42109                        │
│  Version : 0.3.18                       │
│  Daemon  : ~/.cargo/bin/virtuoso-daemon │
├─────────────────────────────────────────┤
│  Terminal: vcli skill exec 'version()'  │
│  Sessions: vcli session list            │
└─────────────────────────────────────────┘

Add to ~/.cdsinit for automatic loading on Virtuoso startup:

load("/path/to/virtuoso-cli/resources/ramic_bridge.il")

2. Connect from terminal:

vcli session list                                        # list active sessions
vcli skill exec 'getCurrentTime()'                       # auto-connects if single session
vcli --session eda-meow-2 skill exec 'getCurrentTime()' # specify session explicitly

Remote mode:

vcli init           # generate .env template
# edit .env: set VB_REMOTE_HOST, VB_SPECTRE_CMD (absolute path)
vcli tunnel start
vcli skill exec 'getCurrentTime()'
vcli tunnel stop

Remote async simulation:

vcli sim run-async --netlist my_tb.scs   # launch on remote server, return immediately
vcli sim job-list                        # check all jobs (auto-refreshes status via SSH)
vcli sim job-status <id>                 # detailed status for one job
vcli sim job-cancel <id>                 # kill remote spectre process

Maestro ADE Explorer (IC23.1+):

# IC23.1 unified ADE uses "maestro" view (formerly adexl/ade_xl)
vcli maestro open --lib myLib --cell myCell            # defaults to view=maestro
vcli maestro set-var --session fnxSession4 --name W --value 10u
vcli maestro run --session fnxSession4                 # async run
vcli maestro export --session fnxSession4 --path out.csv

Multi-Session Operations:

vcli skill broadcast 'getVersion(t)'            # Same SKILL on all sessions
VB_SESSION=eda-meow-1 vcli maestro run ...      # Different tasks via subagents

Multi-Session Architecture

Virtuoso-1 → vcli() → daemon on port 42109 → session: eda-meow-1
Virtuoso-2 → vcli() → daemon on port 51337 → session: eda-meow-2

Terminal A: vcli skill exec '...'                  # auto-selects (single session)
Terminal B: vcli --session eda-meow-2 skill exec   # explicit selection

Session files: ~/.cache/virtuoso_bridge/sessions/<id>.json

Command Reference

vcli [--profile P] [--session S] [--format json|table]
├── init                              Generate .env config template
├── session                           Manage bridge sessions
│   ├── list                              List all active sessions
│   ├── show [id]                         Show session details
│   ├── current                           Show which session would be auto-selected
│   ├── cleanup                           Remove stale session files for dead daemons
│   └── history <id> [--skill] [--cmd] [--limit N]   SKILL + CLI history for a session
├── tunnel                            Manage SSH tunnel
│   ├── start [--timeout N] [--dry-run]
│   ├── stop [--force] [--dry-run]
│   ├── restart [--timeout N]
│   ├── status
│   └── diagnose                          Full connection diagnostics
├── skill                             Execute SKILL code
│   ├── exec <code> [--timeout N]
│   ├── load <file>
│   └── broadcast <code>              Fan out to all live sessions in parallel
├── cell                              Manage cellviews
│   ├── open --lib L --cell C [--view V] [--mode M] [--dry-run]
│   ├── save / close / info
├── schematic                         Schematic editing & reading
│   ├── open / save / check / build --spec file.json
│   ├── place / wire / conn / label / pin
│   ├── list-instances / list-nets / list-pins
│   └── get-params --inst M1
├── maestro                           Maestro ADE Explorer (maestro view) sessions
│   ├── open --lib L --cell C
│   ├── close / list-sessions / save
│   ├── set-var / get-analyses / add-output
│   ├── run / export
├── sim                               Simulation
│   ├── setup / run / measure / sweep / corner
│   ├── run-async --netlist file.scs
│   ├── job-status / job-list / job-cancel
│   └── results / netlist
├── design                            gm/Id sizing tools
│   ├── size / explore
├── process                           Process characterization
│   └── char [--netlist]
└── schema [--all] [noun] [verb]      Output command schema (for Agent discovery)

Configuration

Variable Default Description
VB_SESSION — Target session ID (for multi-instance)
VB_PORT per-user hash Direct port (fallback when no session file)
VB_REMOTE_HOST — SSH remote hostname or alias
VB_REMOTE_USER current user SSH login username
VB_JUMP_HOST — Bastion/jump host address
VB_TIMEOUT 30 Connection/execution timeout (seconds)
VB_PROFILE — Config profile (reads VB_*_<profile> vars)
RB_DAEMON_PATH auto-detected Override daemon binary path

How It Works

Terminal                      Virtuoso Process
────────                      ────────────────

vcli skill exec "1+2"
      │
      │ TCP: {"skill":"1+2"}
      ├──────────────────► virtuoso-daemon (port 42109)
      │                          │
      │                          │ evalstring("1+2")
      │                          │
      │ TCP: "3"
      ◄──────────────────────────┘

Session registration flow:

vcli() in CIW
  → RBStart(): ipcBeginProcess(daemon, port=0)
  → OS assigns port N; daemon prints "PORT:N" to stderr
  → RBIpcErrHandler: RBPort=N, writes session file
  → ~/.cache/virtuoso_bridge/sessions/<id>.json

vcli session list  # reads session files
vcli skill exec    # connects to port N

中文

从任何地方控制 Cadence Virtuoso，本地或远程均可。为 AI Agent 和人类共同设计。

基于 virtuoso-bridge-lite（作者 Arcadia-1）重构。 vcli 是对该项目的完整 Rust 重写与大幅扩展，新增了多 session 支持、动态端口分配、session 注册表、Agent 原生 CLI 以及 Spectre 仿真集成。

简介

vcli 是一个用 Rust 编写的轻量级桥接工具，用于在 Virtuoso 外部执行 SKILL 代码。它通过 ramic_bridge.il 在 Virtuoso 内启动一个 Rust daemon，并通过 TCP 接收来自 CLI 的命令，调用 evalstring 执行 SKILL 并返回结果。

核心特性

  • 多 session 支持 — 同一台服务器上可同时运行多个 Virtuoso 实例，每个实例自动分配唯一 session_id 和随机端口，互不干扰
  • 多 session 并发广播 — vcli skill broadcast 通过 scoped threads 并发广播到所有活跃 session；subagent 模式支持不同 session 执行不同多步工作流
  • 动态端口分配 — daemon 绑定端口 0（OS 自动分配），彻底避免端口冲突
  • session 自动发现 — 只有一个 session 时无需指定；多个 session 时通过 --session 或 VB_SESSION 选择；已死亡的 daemon 对应的 session 文件自动过滤
  • Session 历史记录 — 每个 session 独立保存 SKILL 执行日志和 CLI 命令历史，断线重连后可恢复（vcli session history <id>）
  • 三种编程方式 — 原始 SKILL 表达式、高阶 API、或直接加载 .il 文件
  • 本地+远程模式 — 支持本地直连或 SSH 隧道（ControlMaster 连接复用）
  • Agent 原生 CLI — noun-verb 命令结构、JSON 结构化输出、schema 自省、语义化退出码
  • 原理图编辑与读取 — 创建、放置、连线 + 读取实例/网络/引脚/参数
  • Maestro ADE 管理 — 打开/关闭 Explorer（maestro view）session、设置变量、运行仿真、导出结果（IC23.1+ 统一 ADE）
  • Spectre 仿真 — 同步/异步仿真、Job 注册与状态跟踪、PSF 结果解析
  • 多 Profile 支持 — --profile 参数支持同时连接多个 Virtuoso 实例
  • 命令日志 — 所有 SKILL 调用记录到 ~/.cache/virtuoso_bridge/logs/commands.log
  • 交互式 TUI — vtui 终端仪表盘，实时显示 session、仿真 job、隧道状态

安装

从 crates.io 安装（推荐）：

cargo install virtuoso-cli                          # vcli（主 CLI）
cargo install virtuoso-cli --bin vtui               # vtui（交互式 TUI 仪表盘）
cargo install virtuoso-cli --features daemon        # virtuoso-daemon（bridge 后端）

从源码安装：

git clone https://github.com/deanyou/virtuoso-cli.git
cd virtuoso-cli
cargo install --path .

安装后 vcli 和 virtuoso-daemon 均位于 ~/.cargo/bin/。

注意：不要将 CLI 命名为 virtuoso，与 Cadence Virtuoso 二进制名冲突。

快速开始

第一步：在 Virtuoso CIW 中加载 RAMIC Bridge：

load("/path/to/virtuoso-cli/resources/ramic_bridge.il")

load 会自动停止旧 daemon、将路径重置为 ~/.cargo/bin/virtuoso-daemon 并重启，首次加载和更新后重载均适用。

输出：

┌─────────────────────────────────────────┐
│  vcli (Virtuoso CLI Bridge) — Ready     │
├─────────────────────────────────────────┤
│  Session : eda-meow-1                   │
│  Port    : 42109                        │
│  Version : 0.3.18                       │
│  Daemon  : ~/.cargo/bin/virtuoso-daemon │
├─────────────────────────────────────────┤
│  Terminal: vcli skill exec 'version()'  │
│  Sessions: vcli session list            │
└─────────────────────────────────────────┘

在 ~/.cdsinit 中加入以下内容，实现 Virtuoso 启动时自动加载：

load("/path/to/virtuoso-cli/resources/ramic_bridge.il")

第二步：从终端连接：

vcli session list                                        # 查看所有活跃 session
vcli skill exec 'getCurrentTime()'                       # 单 session 时自动连接
vcli --session eda-meow-2 skill exec 'getCurrentTime()' # 多 session 时指定目标

远程模式：

vcli init           # 生成 .env 配置模板
# 编辑 .env：设置 VB_REMOTE_HOST、VB_SPECTRE_CMD（绝对路径）
vcli tunnel start
vcli skill exec 'getCurrentTime()'
vcli tunnel stop

远程异步仿真：

vcli sim run-async --netlist my_tb.scs   # 在远程服务器启动仿真，立即返回
vcli sim job-list                        # 查看所有 job（通过 SSH 自动刷新状态）
vcli sim job-status <id>                 # 查看单个 job 详情
vcli sim job-cancel <id>                 # 终止远程 spectre 进程

Maestro ADE Explorer（IC23.1+）：

# IC23.1 统一 ADE 使用 "maestro" view（旧版本为 adexl/ade_xl）
vcli maestro open --lib myLib --cell myCell            # 默认 view=maestro
vcli maestro set-var --session fnxSession4 --name W --value 10u
vcli maestro run --session fnxSession4                 # 异步运行
vcli maestro export --session fnxSession4 --path out.csv

多 session 并发操作：

vcli skill broadcast 'getVersion(t)'            # 同一 SKILL 广播到所有 session
VB_SESSION=eda-meow-1 vcli maestro run ...      # 通过 subagent 实现不同任务

多 Session 工作原理

Virtuoso-1 → vcli() → daemon on port 42109 → session: eda-meow-1
Virtuoso-2 → vcli() → daemon on port 51337 → session: eda-meow-2

终端 A: vcli skill exec '...'                  # 自动连接（单 session）
终端 B: vcli --session eda-meow-2 skill exec   # 显式指定

Session 注册文件保存在 ~/.cache/virtuoso_bridge/sessions/<id>.json。

命令参考

vcli [--profile P] [--session S] [--format json|table]
├── init                              创建 .env 配置模板
├── session                           管理 bridge session
│   ├── list                              列出所有活跃 session
│   ├── show [id]                         查看 session 详情
│   ├── current                           显示会被自动选中的 session
│   ├── cleanup                           删除已死亡 daemon 的 session 文件
│   └── history <id> [--skill] [--cmd] [--limit N]   查看 SKILL + CLI 历史
├── tunnel                            管理 SSH 隧道
│   ├── start / stop / restart / status
│   └── diagnose                          完整连接诊断
├── skill                             执行 SKILL 代码
│   ├── exec <code> [--timeout N]
│   ├── load <file>
│   └── broadcast <code>              并发广播到所有活跃 session
├── cell                              管理 cellview
│   ├── open / save / close / info
├── schematic                         原理图编辑与读取
│   ├── open / save / check / build --spec file.json
│   ├── place / wire / conn / label / pin
│   ├── list-instances / list-nets / list-pins
│   └── get-params --inst M1
├── maestro                           Maestro ADE Explorer（maestro view）仿真
│   ├── open / close / list-sessions / save
│   ├── set-var / get-analyses / add-output
│   ├── run / export
├── sim                               仿真
│   ├── setup / run / measure / sweep / corner
│   ├── run-async / job-status / job-list / job-cancel
│   └── results / netlist
├── design                            gm/Id 设计工具
├── process                           工艺表征
└── schema [--all] [noun] [verb]      输出命令 schema（供 Agent 发现）

配置说明

变量 默认值 说明
VB_SESSION - 目标 session ID（多实例时使用）
VB_PORT 按用户名 hash 直连端口（无 session 文件时的回退值）
VB_REMOTE_HOST - SSH 远程主机名或别名
VB_REMOTE_USER 当前用户 SSH 登录用户名
VB_JUMP_HOST - 跳板机/堡垒机地址
VB_TIMEOUT 30 连接/执行超时（秒）
VB_PROFILE - 配置 profile（读取 VB_*_<profile> 变量）
RB_DAEMON_PATH 自动检测 覆盖 daemon 二进制路径

工作原理

终端                          Virtuoso 进程
────                          ─────────────

vcli skill exec "1+2"
      │
      │ TCP: {"skill":"1+2"}
      ├──────────────────► virtuoso-daemon (port 42109)
      │                          │
      │                          │ evalstring("1+2") → "3"
      │                          │
      │ TCP: "3"
      ◄──────────────────────────┘

Session 注册流程：

vcli() in CIW
  → RBStart(): ipcBeginProcess(daemon, port=0)
  → OS 分配端口 N；daemon 打印 "PORT:N" 到 stderr
  → RBIpcErrHandler: RBPort=N，写入 session 文件
  → ~/.cache/virtuoso_bridge/sessions/<id>.json

vcli session list  # 读取 session 文件
vcli skill exec    # 连接到端口 N

License / 许可证

MIT License — see LICENSE

About

virtuoso bridge and CLI for AI agent

Resources

Readme

License

MIT license
Activity

Stars

24 stars

Watchers

1 watching

Forks

8 forks
Report repository

Releases 29

v0.4.0-alpha.4 Latest
May 10, 2026
+ 28 releases

Packages

 
 
 

Contributors

Languages