CLI Execution Guide (kinenix)
This guide documents the Command Line Interface (CLI) for kinenix, powered by the kinenix runner in kinenix-core.
1. Installation
From PyPI (see the Quickstart):
From a clone of the repository, for development, in editable mode:
Verify that the CLI is accessible:
2. Core Commands
2.1 Check Version and Environment (version)
Outputs runtime details including kinenix version, Python runtime, operating system, and architecture:
2.2 Install Playwright Browsers (install-browsers)
Downloads the Chromium browser binary required for Web automation tasks:
(Note: kinenix also detects missing browser binaries and automatically downloads Chromium on the first web flow execution).2.3 Start a Project (init)
Projects are created in your flows folder, separate from the Kinenix source code (default ~/kinenix-flows; see Where your flows live). The first kinenix init at a terminal asks where it should be and whether to make it a git repository; scripts and CI use the default without asking. Every project in it runs by name from any folder.
For a new task, give it a name. The folder is derived from the name (Get stock data becomes get_stock_data; Thai names work):
kinenix init "Get stock data"
kinenix init "Get stock data" --dir C:\bots\stocks # choose the folder yourself
| Created file | Purpose |
|---|---|
requirements.md | The requirements (RQ), with sections to fill in: goal, steps, changeable settings, secrets, output, errors, schedule |
AGENTS.md, CLAUDE.md | Instructions for the AI assistant that turns requirements.md into flow.md: spec links, kinenix actions, config and secret rules, and kinenix validate before handing back |
flow.md | A one-step placeholder flow named after the task, so validate and run work from the start |
config/config.json | Empty settings ({}) |
.env.example, .gitignore | Where secrets go, and keeping .env, output/, and logs/ out of git |
README.md | The workflow: requirements, AI assistant, validate, run |
The intended workflow: write requirements.md, open the folder in an AI assistant and ask it to build the flow, then kinenix validate and kinenix run.
To copy a complete example instead, use --example. The folder must not exist or must be empty; nothing is overwritten.
kinenix init --list # examples, and which need a browser
kinenix init demo --example hello # no browser, no internet: the quickest installation check
kinenix init fx --example bot_fx_rate
kinenix run demo
| Example | What it does |
|---|---|
hello | Builds a greeting table from config.json and writes a CSV; the quickest installation check |
bot_fx_rate | Bank of Thailand transfer rates for chosen currencies and dates to CSV, with email (needs a browser) |
rpachallenge | Fills the RPA Challenge form from an Excel file (needs a browser) |
The examples are copies of flows/examples/ in the repository, kept identical by .github/scripts/sync_examples.py and a test.
2.4 Show or Change the Flows Folder (flows-dir)
kinenix flows-dir # where flows are kept, and where that setting comes from
kinenix flows-dir D:\bots\flows # change it (saved in ~/.kinenix/kinenix.env)
Order of precedence: the KINENIX_FLOWS_DIR environment variable, then the saved setting, then ~/kinenix-flows.
2.5 List Actions and Their Parameters (actions)
Prints every action with the parameters it accepts, from the code itself. Useful while writing flow.md, and for AI assistants that need exact parameter names:
2.6 List Available Flows (list)
Scans the current folder, your flows folder (kinenix flows-dir), and a repository's flows/ and examples/ folders, and lists every runnable flow and project bundle:
2.7 Run a Flow (run)
Executes an automation flow using the Smart Flow Resolver. You can specify a flow by alias, project folder, relative path, or absolute path:
# Run by alias or bundle name
kinenix run rpachallenge
# Run by namespace
kinenix run examples/rpachallenge
# Run by direct file path
kinenix run flows/examples/rpachallenge
3. Command Options & Parameters
3.1 Override / Inject Variables (--vars)
Pass external variables or runtime overrides to a flow as a JSON string:
Inside the flow, these variables can be accessed using the standard expression syntax ${target_url}.
3.2 Custom Log Directory (--log-dir)
By default, Kinenix automatically detects the project root and writes structured JSON logs into <project_root>/logs/. You can override this location using --log-dir:
3.3 Send Telemetry to the Hub (kinenix connect, --hub)
Connect a machine once, and every run on it uploads its execution log to that Hub:
kinenix connect http://<hub-ip>:8080 # asks for the key, checks it, saves it in ~/.kinenix/kinenix.env
kinenix connect # the Hub in use; kinenix connect --off stops reporting
For one run only, --hub sets the Hub URL. If the Hub requires an API key and none is saved, set KINENIX_HUB_API_KEY first:
See the Kinenix Hub Guide for setup details.
3.4 Ask the Hub About Runs (kinenix hub query)
Reads runs, steps, and failures from the Hub database, read-only. On the Hub machine it reads hub.db directly; --url asks a Hub on another machine.
kinenix hub report --flow "BOT FX" # how the latest run of a flow went
kinenix hub logs --flow "BOT FX" # every step of that run
kinenix hub query --list # what can be queried
kinenix hub query v_failures --since yesterday # what failed, where, on which item
kinenix hub query "SELECT flow_name, COUNT(*) FROM v_runs GROUP BY flow_name"
Options, safety rules, and user views: hub.md, Querying Runs. Columns: hub_data.md.
4. Smart Flow Resolver Behavior
When running kinenix run <input>, the resolver searches candidate paths in the following priority order:
- Exact File Path: Resolves directly if
<input>is an existing file path. - Project Bundle Directory: If
<input>is a directory containingflow.md, executes<input>/flow.md. - Appended
.json: Checks if<input>.jsonexists. - Discovered Flow Alias: Matches aliases discovered by
kinenix list. - Project Search Directories: Searches candidate subdirectories (
flows/,examples/,~/.kinenix/flows/).
5. Running Automated Unit Tests
To run the automated test suite using pytest: