ExecGov | ExecGov

CLI Guide

CLI ScopeThe CLI can already log in, register scripts, read the manifest, trigger backend execution directly, and print a web-open link.

Web-based upload registration already supports Python / Shell. CLI-based remote registration still centers on Python for now, while remote task pulling and long-running Agent execution remain next-stage work.

execgov-cli is ExecGov's current command-line entry for individual developers, delivery work, and local-execution scenarios. The point is not to build a command-line skin. The point is to connect the local script directory, local runtime environment, and platform control plane into a bridge that is usable today.

The CLI path exists to bridge the external control plane and the local environment so that local scripts, execution environments, and the platform governance chain can work together.

loginregisterlist / runagent describe / start

Local onboarding / lead routing View capabilities

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

Already implemented

login
register
list
run
agent describe / agent start
sidecar JSON overrides, metadata extraction from comments / docstrings / filenames
.execgov-manifest.json generation

Not Yet

Not implemented yet

pull / publish / doctor
agent heartbeat / agent status / agent run
remote task pulling and execution-log upload
richer CLI-side remote registration for more non-Python asset types

Positioning

Its role inside the platform

The local onboarding entry for individual developers and technical users
A delivery tool for organizing a script directory and generating the manifest
The skeleton starting point for the Agent direction, not a finished Agent product
The first bridge layer between the platform control plane and the local runtime environment

Public Onboarding

How the CLI relates to the public entry

New users should first feel the execution chain through the no-login web experience page, then decide whether to continue into signup / login.
The CLI is a deeper local-bridge entry. It does not replace the public /experience path.
It fits users who already know they want to connect local scripts and local runtime environments to the platform control plane.

Web Entry

How the CLI works with the web entry

The web side already exposes three formal entry points: /experience, /login, and /register.
After registration succeeds, the flow currently goes through /register/result before returning to login and the personal mainline.
The experience page is for feeling the execution chain first, not for real business writes. The left panel currently shows Python task_brief_demo.py, while the right panel shows Shell clean_log_demo.sh.
Web-side upload registration already supports .py / .sh / .bash.
execgov-cli is already moving toward Python / Shell compatibility, but the main directory-registration example, default explanation, and quickstart wording still center on Python for now.

CLI In Path

Which of the four paths the CLI belongs to most

Path	The CLI's role	How to understand it
Free path	Not the default entry	People touching the platform for the first time should begin with the web experience and signup flow instead of starting with the CLI.
Local script-slot expansion	The local bridge for continued individual use	It fits people who are already continuously connecting scripts in their personal space and want to organize the directory, generate the manifest, and test execution.
Standard team edition	Auxiliary onboarding and supplemental local execution	The main entry for the team edition is still the formal tenant frontend. The CLI acts more like a bridge than the formal team entry itself.
Enterprise delivery	The bridge layer for local environments and intranet resources	The CLI / Agent path becomes more critical when the project involves local environments, intranet resources, or hybrid execution.

Quick Start

Quick start

1. Install in a development environment

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

This is the installation path that fits development, local testing, and local onboarding best right now. After installation, you no longer need to type python -m execgov_cli.cli every time.

2. Run the module entry directly

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

If you have not installed it locally yet, start by running the module entry directly.

3. Save login configuration

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

The default config file path is ~/.execgov/config.json. You can override it through EXECGOV_CONFIG_DIR.

4. Register a script directory

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

The command scans the directory, generates .execgov-manifest.json, and by default calls the backend upload-register API. CLI-side directory registration is already moving toward Python / Shell compatibility, but the primary examples and default guidance still center on Python for now. The web entry already supports both Python and Shell along the same path.

Common Commands

Common commands

Inspect results without writing files

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

Useful when you want to confirm whether the extracted Skill metadata looks right before writing anything.

Generate only the manifest

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

If you do not want to call the backend yet, generate the local manifest only.

Read a manifest summary

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

list currently requires an explicit workspace path, and that directory must already contain .execgov-manifest.json.

Trigger a Skill directly

python -m execgov_cli.cli run backup_local \
  --request-text "Manual backup run from CLI" \
  --input-json '{"sourcePath":"/tmp/demo"}'

If you saved --web-base during login, the CLI will also print the corresponding web-open link.

View the Agent description

python -m execgov_cli.cli agent describe

This currently prints the local Agent description so the platform side can wire up later execution endpoints.

Reserve the local Agent mode

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

At the moment, this writes execution_mode into the manifest and keeps the local Agent entry alive, but it does not yet take over real execution.

Metadata

Metadata extraction rules

First read the matching sidecar file: <script_stem>.execgov-skill.json
Then read top-of-file comments or the top Python docstring
Finally infer from the filename when no better metadata is available

The manifest currently includes at least script_code, skill_name, description, risk_level, timeout_seconds, execution_mode, and inputs.

Current Rules

Limits you should know in advance

register is not manifest-only by default. It will really call the backend registration API.
Web-side upload registration already supports Python / Shell. The CLI directory-registration path is catching up on Shell, but the official mainline wording still centers on Python for now.
run calls the backend manual-execution API directly and prints a web-open link when available.
Remote task pulling, long-running local execution, and execution-log upload belong to the next phase.

Next Read

Continue with product positioning, or move directly into the local onboarding conversation

Continue with Product Overview, Capabilities, and Deployment. If you already have a script directory, you can also bring the onboarding question directly into a conversation.

ProductProduct Overview CapabilitiesCapabilities DeploymentDeployment LeadLocal onboarding / lead routing