CLI Guide

CLI 指引

CLI ScopeCLI 已经能登录、注册脚本、读取 manifest、直接触发后端执行，并输出 Web 打开链接。

网页端上传注册已经支持 Python / Shell；CLI 远程注册当前仍以 Python 为主，远程任务拉取和 Agent 常驻执行仍属于下一阶段。

execgov-cli 是 ExecGov 当前面向个人开发者、交付实施和本地执行场景的命令行入口。这条线的重点不是“做一个命令行皮肤”，而是把 本地脚本、本地环境和平台控制面 接成一条现在能用的桥。

CLI 这条线承接的是平台外部控制面与本地环境之间的桥接，用来把本地脚本、执行环境和平台治理链路接起来。

loginregisterlist / runagent describe / start

EXECGOV // CLI BRIDGEDOC 07

const accountFlow = ['login', 'register', 'config']const workspaceFlow = ['manifest', 'metadata', 'upload_register']const executionFlow = ['run', 'agent_describe', 'agent_start']

LOCAL WORKSPACE / PLATFORM CONTROL

Implemented

当前已实现

login
register
list
run
agent describe / agent start
sidecar JSON 覆盖、注释 / docstring / 文件名元数据提取
.execgov-manifest.json 生成

Not Yet

当前未实现

pull / publish / doctor
agent heartbeat / agent status / agent run
远程任务拉取与执行日志回传
CLI 侧更多非 Python 类型的真实远程上传注册

Positioning

它在平台里的角色

个人开发者和技术用户的本地接入入口
项目交付时整理脚本目录、生成 manifest 的工具
Agent 方向的骨架起点，而不是成熟产品
把控制面和本地环境接起来的第一层桥接接口

Public Onboarding

CLI 和公开入口的关系

陌生用户先从 Web 免登录体验页感受执行链路，再决定是否继续注册 / 登录。
CLI 是更深一层的本地接入入口，不替代 /experience 这条公开体验路径。
适合已经确认要把本地脚本、本地环境和平台控制面接起来的用户继续往下走。

Web Entry

CLI 与 Web 入口如何配合

网页端已经提供 /experience、/login、/register 三个正式入口。
注册成功当前会先进入 /register/result 结果页，再回到登录与个人主链路。
体验页用于先感受执行链路，不承接真实业务写入；当前左侧是 Python `task_brief_demo.py`，右侧是 Shell `clean_log_demo.sh`。
网页端上传注册当前已支持 .py / .sh / .bash。
execgov-cli 当前已经开始兼容 Python / Shell，但目录注册的主示例、默认讲解和快速上手口径暂时仍以 Python 为主。

CLI In Path

CLI 在四层路径里更偏哪一层

路径	CLI 的角色	该怎么理解
免费线	不是默认入口	第一次接触平台的人先走 Web 体验和注册，不需要一上来就用 CLI。
本地脚本位增购	个人持续使用的本地桥接工具	适合已经在个人空间持续接脚本的人继续整理目录、生成 manifest 和测试执行。
标准团队版	辅助接入和补充本地执行能力	团队版主入口仍是正式租户前端，CLI 更像桥接工具，不是正式团队入口本身。
企业交付	本地环境 / 内网资源桥接层	当项目涉及本地环境、内网资源或混合执行时，CLI / Agent 才会变得更关键。

Quick Start

快速开始

1. 开发环境安装

cd execgov-cli
python -m pip install -e .
execgov-cli --help

这是当前最适合开发、自测和本地接入的安装方式。安装完成后就不必每次都写 python -m execgov_cli.cli。

2. 直接运行入口

cd execgov-cli
python -m execgov_cli.cli --help

如果你还没做本地安装，可以先直接用模块方式运行。

3. 保存登录配置

cd execgov-cli
python -m execgov_cli.cli login \
  --token YOUR_API_TOKEN \
  --api-base http://localhost:6089/dev-api \
  --web-base http://localhost:80

默认配置文件路径是 ~/.execgov/config.json，也可以通过 EXECGOV_CONFIG_DIR 覆盖。

4. 注册脚本目录

python -m execgov_cli.cli register ./examples/scripts

命令会扫描目录、生成 .execgov-manifest.json，并默认调用后端 upload-register。当前 CLI 目录注册已经开始兼容 Python / Shell，但主示例和默认讲解暂时仍以 Python 为主；网页端同一条入口已支持 Python / Shell。

Common Commands

常用命令

只看结果，不落盘

python -m execgov_cli.cli register ./examples/scripts --dry-run --print-json

适合先确认提取出的 Skill 元数据是否符合预期。

只生成 manifest

python -m execgov_cli.cli register ./examples/scripts --manifest-only

如果你当前不想请求后端接口，可以先只生成本地清单。

查看 manifest 摘要

python -m execgov_cli.cli list ./examples/scripts

list 当前必须显式传入 workspace，而且该目录下需要已存在 .execgov-manifest.json。

直接触发 Skill 执行

python -m execgov_cli.cli run backup_local \
  --request-text "CLI 手动执行备份" \
  --input-json '{"sourcePath":"/tmp/demo"}'

如果登录时保存了 --web-base，CLI 会额外输出对应的 Web 打开链接。

查看 Agent 描述

python -m execgov_cli.cli agent describe

当前主要用于输出本地 Agent 描述信息，方便平台侧对接后续执行端。

预留本地 Agent 模式

python -m execgov_cli.cli register ./examples/scripts --execution-mode local-agent
python -m execgov_cli.cli agent start

现在会把 execution_mode 写入 manifest，并保留本地 Agent 入口，但还不会真的接管执行。

Metadata

元数据提取规则

优先读取同名 sidecar 文件：<script_stem>.execgov-skill.json
其次读取脚本顶部注释或 Python 顶部 docstring
最后再从文件名自动推断

当前 manifest 中至少会包含 script_code、skill_name、description、risk_level、timeout_seconds、execution_mode 和 inputs 等字段。

Current Rules

需要提前知道的限制

register 默认不是只落本地 manifest，而是会真正请求后端注册接口
网页端上传注册已支持 Python / Shell；CLI 这条目录注册路线也在补齐 Shell，但当前官方主口径暂时仍以 Python 为主
run 会直接调用后端手动执行接口，并输出可打开的 Web 链接
远程任务拉取、本地常驻执行和日志回传属于下一阶段

Next Read

继续查看产品定位，或直接进入本地接入沟通

可继续查看产品概览、核心能力和部署方式；已有脚本目录时，也可直接带着接入问题进入沟通。

Product产品概览 Capabilities核心能力 Deployment部署方式 Lead本地接入 / 线索分流