ExecFabric | ExecFabric

CLI & Local Agent Guide

Minimal Formal LoopThe CLI already supports login, cloud registration, local-agent registration, direct run, machine binding, and Local Agent polling and execution on the current machine.

The web path is still the best place to feel a visible single-file flow first. The CLI is the deeper path for single-file or folder registration, local-path registration, and local execution bridging.

execfabric-cli is ExecFabric's current command-line entry for individual developers, delivery work, and local or intranet execution scenarios. The point is not to add a command-line skin. The point is to connect the local script folder, local runtime environment, and platform control plane into a bridge that is usable today.

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

loginregisterlist / runagent bind / describe / start

Local onboarding / lead routing View capabilities

EXECFABRIC // CLI BRIDGEDOC 07

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

LOCAL WORKSPACE / PLATFORM CONTROL

Implemented

Already implemented

login
register
list
run
agent describe, agent bind, and agent start
sidecar JSON overrides and metadata extraction from comments, docstrings, and file names
.execfabric-manifest.json generation
register --execution-mode cloud calling backend upload-register for Python, Shell, Bat(Cmd), and Node.js upload registration; multi-file workspaces are packaged and registered with an explicit entry file
register --execution-mode local-agent calling backend local-register for single-file or folder local-path registration
agent start polling, claiming, executing, and completing Local Agent jobs on the current machine

Not Yet

Not implemented yet

pull, publish, and doctor
agent heartbeat, agent status, and agent run
streaming log upload and deeper multi-machine scheduling
richer cloud upload registration for more non-script asset types beyond today's Python, Shell, Bat(Cmd), and Node.js path

Positioning

Its role inside the platform

The deeper local onboarding entry for individual developers and technical users
A delivery tool for organizing a script folder and generating the manifest
The first bridge layer between the platform control plane and the local runtime environment
The current minimal Local Agent loop, not a finished general Agent product

Public Onboarding

How the CLI relates to the public entry

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

Web Entry

How the CLI works with the web entry

The formal public web entry is now split between the experience entry at https://execfabric.cn/#/experience and the unified login / signup entry at https://execfabric.cn/.
After signup succeeds, the current flow still goes through a dedicated handoff page before returning to login and the personal mainline.
The experience page is for feeling the execution chain first. The left panel currently shows the Python demo task_brief_demo.py, while the right panel shows the Shell demo clean_log_demo.sh.
Web-side upload registration already supports .py, .sh, and .bash.
The web path fits visible single-file onboarding best. The CLI takes over when you need repeatable single-file or folder registration, local-path registration, or Local Agent execution.

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 personal space and want to organize folders, generate the manifest, or keep scripts local while letting the platform dispatch them back.
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 as a bridge rather than the formal team entry itself.
Enterprise delivery	The bridge layer for local environments and intranet resources	The CLI / Local Agent path becomes more critical when the project involves local environments, intranet resources, or hybrid execution.

Cloud Mode

What `cloud` registration does today

The CLI scans the workspace, extracts metadata, generates .execfabric-manifest.json, and calls backend upload-register
Python, Shell, Bat(Cmd), and Node.js scripts currently go through the real cloud upload-registration path
Cloud execution of bat / cmd still requires a Windows runtime, so non-Windows servers will fail clearly at execution time
This is the path for putting script content into the platform-side registration flow

Local-Agent Mode

What `local-agent` registration does today

The CLI calls backend local-register and records the local path instead of uploading source code
The same command supports a whole folder or a single script file
Python, Shell, Bat, and Node local paths can currently be registered into this mode
The current machine's machine_id, machine_name, and agent_name are registered together for later job routing

Quick Start

Quick start

1. Install it into the current environment

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

This is the most practical path right now for development, local testing, and delivery-side validation. The outward standard command is execfabric-cli.

2. Save the login configuration

execfabric-cli login \
  --token YOUR_API_TOKEN \
  --api-base https://execfabric.cn/prod-api \
  --web-base https://execfabric.cn

The default config file is ~/.execfabric/config.json. Free developers should normally point to the personal-free tenant domain. Enterprise users should point to their own tenant domain. public is not the default ordinary CLI user entry.

3. Register a workspace in cloud mode

execfabric-cli register ./examples/scripts

The command scans the folder, generates .execfabric-manifest.json, and calls backend upload-register. Multi-file workspaces declare an explicit entry file in the manifest, which is equivalent to choosing a zip package in the Web UI and filling entryFile. Python, Shell, Bat(Cmd), and Node.js already go through the real cloud-registration path. Cloud execution of bat / cmd still requires a Windows runtime.

4. Register local scripts and start the Local Agent

execfabric-cli register ./examples/scripts --execution-mode local-agent
execfabric-cli register ./examples/scripts/backup.py --execution-mode local-agent
execfabric-cli agent start

This keeps code on the current machine, registers either a folder or a single file, and lets the current machine claim and execute the queued Local Agent jobs that were routed back to it.

Common Commands

Common commands

Inspect results without writing files

execfabric-cli register ./examples/scripts --dry-run --print-json

Useful when you want to verify whether the extracted Skill metadata looks correct before writing anything.

Generate only the manifest

execfabric-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

execfabric-cli list ./examples/scripts

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

Trigger a Skill directly

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

If --web-base was saved during login, the CLI also prints the corresponding web-open link for that execution.

Describe or bind the current machine

execfabric-cli agent describe
execfabric-cli agent bind \
  --machine-name "Alice MacBook" \
  --agent-name "alice-local-agent"

agent bind persists a stable machine identity for later local registration and Local Agent routing. If you do not bind it manually, login and Local Agent commands still fill in defaults.

Process the Local Agent queue once

execfabric-cli agent start --once

This is the easiest manual test for the Local Agent loop. It claims at most one job, executes it on the current machine, and reports completion back to the platform.

Metadata

How metadata and sidecar files work

Sidecar file naming

backup.py
backup.execfabric-skill.json
.execfabric-manifest.json

The standard sidecar file name is <script_stem>.execfabric-skill.json, and the workspace manifest is .execfabric-manifest.json.

Extraction rule

The CLI first extracts metadata from comments, docstrings, and file names, then applies explicit sidecar overrides, and finally writes the workspace summary into the manifest.

This is why the CLI can act as both a registration tool and a lightweight local delivery organizer.

Current Boundary

What the CLI already proves today

The CLI is not limited to local manifest generation anymore. It already calls real backend registration and execution interfaces.
The minimal formal local loop is already live: local scripts can be registered, claimed back to the same machine, executed there, and completed back to the platform.
The web entry is still best for visible single-file onboarding. The CLI is better for repeatable registration, folder onboarding, and local-path dispatch.

Later Boundary

What still belongs to later enhancement

General operational governance around heartbeat, status, richer Agent control, and deeper multi-machine scheduling
Streaming execution-log upload instead of simple completion-summary reporting
A fuller cloud-registration path for more asset types beyond today's Python, Shell, Bat(Cmd), and Node.js mainline

Next Read

Read the CLI together with scenarios, deployment, and onboarding prep

The CLI becomes easier to judge when you read it together with local execution scenarios, deployment shape, and the onboarding checklist instead of treating it like a standalone tool page.

ScenariosScenarios Deployment & Delivery BoundariesDeployment & Delivery Boundaries ChecklistOnboarding Checklist LeadDiscuss local onboarding