from install to your
first governed run.

five minutes. one CLI. every action contract-bound and recorded from the first keystroke. no config sprawl, no hand-rolled logging.

get started browse connectors

01 / install 02 / first run 03 / core concepts 04 / three commands 05 / gated runs

// 01 · install

one command. no venv wrangling.

CLIable ships as a standalone Python tool. Install it globally with uv tool install — no virtual environment to activate, no PATH gymnastics. Requires Python 3.14 and uv.

Already have Python 3.14 via pyenv or mise? Run uv tool install cliable and uv handles the isolated environment automatically.

python 3.14 uv required no venv activate

bash

uv tool install cliable

verify

cliable --version
# cliable 0.9.0 (python 3.14)

// 02 · first run

list connectors, then run one.

cliable loads installed connector packages at startup. run connector list to see what's registered, then call a capability directly with run.

agent session — cliable

# discover available connectors

› cliable connector list

connector feishu [email protected] loaded

connector docker [email protected] loaded

connector sql [email protected] loaded

# run a capability — input is a JSON string

› cliable run feishu create_doc --input-json '{"doc_title":"q2 retro","space_key":"eng"}'

# outcome record

outcome succeeded

run_id r_8f2a14

shard local/runs/r_8f2a14.db

capability feishu.create_doc

elapsed 1.23s

_

every run lands in a shard — a local SQLite file scoped to the run. the run_id is stable and addressable after the session ends.

// 03 · core concepts

six nouns. the full runtime vocabulary.

CLIable is built from a small set of precise primitives. understanding these six terms is enough to read any run record or debug any policy decision.

connector

a packaged integration — manifest, contract sidecars, and policy defaults bundled together. the unit of capability discovery and governance configuration.

run

a single capability invocation. immutable once committed. carries input bindings, the policy decision, the outcome, and a link to its shard.

task

a unit of work surfaced to a human or upstream agent. produced when a run is gated or when a multi-step workflow needs an explicit checkpoint.

contract

the typed schema sidecar for a capability — parameter names, types, required fields, and output shape. validates every invocation before it executes.

policy

package-local TOML defaults declaring allow, gate, or deny per capability. the decision travels with the connector, not with the agent caller.

shard

a local SQLite file that holds the run record, task facts, and verifications for a single execution context. two-level: a global index + per-run shards.

// 04 · three commands

three surfaces. the whole runtime.

connector, run, and task map cleanly onto discover, execute, and resolve. learn these three and you have the full CLI surface.

01 / discover

cliable connector

inspect the connector registry. list all loaded packages, read a connector's manifest, and verify that contracts are present before running.

connector list — all loaded packages
connector get <name> — manifest detail
connector capabilities — full capability map

02 / execute

cliable run

invoke a connector capability. the runtime validates the input contract, evaluates policy, executes (or gates), and commits the outcome to the run shard.

run <connector> <cap> — execute
--input-json <json> — bind parameters
run get <run_id> — fetch record

03 / resolve

cliable task

read and act on interaction tasks. a gated run parks as pending until a task is resolved or cancelled — the closure run lands in the same shard.

task list — pending tasks
task get <it_id> — task detail
task resolve | cancel — close the loop

// 05 · gated runs

when policy says gate, the run parks — not fails.

a gated capability returns no_op as its outcome and creates an interaction_task in the pending state. the original run is committed but not executed. nothing is lost.

read the task with task get, decide, then close the loop with task resolve or task cancel. a closure run is committed alongside the updated task — the full trace is sealed.

pending resolved or cancelled

no_op — not an error

a no_op outcome means policy intercepted the action before execution. the run record is valid and complete. the interaction_task carries all context needed for a human or supervisor agent to authorize and resume.

cliable task get it_22b9

{
  "task": "it_22b9",
  "state": "pending",
  "run": "r_9c3d01",
  "capability": "feishu.delete_wiki_node",
  "reason": "requires_authorization",
  "context": { "caller": "cleanup-agent" }
}