Commands exposed through Rune
These are defcli commands in the Flint project. The prefix is rune exe --repo PATH for a working tree or rune exe NAME for a deployed named Rune. Global --json belongs before exe. There is no separate Flint executable.
run --workflow PATH [--format FORMAT]- Reads a repository-bounded workflow file, validates, submits, and drives the run. Formats are
github-actions-yaml, the default, andjson. Explicit JSON requires--format json. status [--run-id ID]- Reads one stored run, or lists runs without the option.
logs --run-id ID --job JOB- Reads one job log with the CLI's 65536 limit.
cancel --run-id ID- Persists cancellation and attempts native cleanup.
health- Reads normalized service, queue, publication, resource, and full-run health.
resources- Lists configured resource pools.
replay --run-id ID- Creates a queued replay linked to the prior run. The handler does not drive the replay.
explain --run-id ID- Explains the stored outcome and references bounded log evidence.
CLI results use Rune's defcli envelope. Domain responses are written as result.json artifacts. A successful handler envelope is not a substitute for reading the stored run's job outcomes.
Workflow formats and limits
JSON workflow graphs use schema_version: 1, name, and a jobs array. Jobs use unique id, a needs array of dependency IDs, and execution steps. Optional job requires names resource pools. Graph validation rejects duplicate IDs, unknown dependencies, cycles, and unsupported conditions.
Actions-style YAML is a supported subset, not complete GitHub Actions compatibility. Top-level keys are name, on, env, defaults, and jobs. Jobs are a mapping with runs-on, env, defaults, steps, needs, if, timeout-minutes, continue-on-error, strategy, services, container, and requires. Unknown keys are rejected.
A step has exactly one of run or uses. Accepted keys also include id, name, if, continue-on-error, timeout-minutes, shell, env, and with. A runner label does not provision another operating system or cloud runner.
The compiler recognizes actions/checkout@v4, actions/cache@v4, actions/upload-artifact@v4, and actions/download-artifact@v4. Other action references require a full lowercase 40-character commit. Docker references, container images, and service images require a lowercase 64-character SHA-256 digest. Service objects use image, command, and env. Operator-staged content and required runtimes must exist before native execution.
Matrix expansion has a 64-job limit. Supported condition handling includes success(), failure(), always(), boolean values and operators, supported literal string functions, and bounded repo-relative hashFiles patterns. Unsupported expressions fail validation. Do not infer full provider expression semantics from a familiar function name.
Job container roots, service roots, JavaScript and composite actions, and Docker actions use operator-owned immutable content. Accepted syntax alone does not prove all images, actions, services, caches, artifacts, or resource hooks are ready on a host.
Operator settings and content
RUNE_NATIVE_ROOTFS- Operator-managed base rootfs for native Linux work.
RUNE_NATIVE_CGROUP_ROOT- Delegated cgroup v2 root available to the service account.
RUNE_NATIVE_STATE_ROOT- Short private native-state root. State is owner-scoped. Cleanup and recovery fail closed.
RUNE_SETTING_FLINT_RESOURCES_JSON- Resource array with
name,slots,grace_seconds, optionalenvironment, and optional acquire and release hooks. RUNE_SETTING_FLINT_REPOSITORIES_JSON- Approved service and repository mappings to workflow objects, with optional checkout credential names. Default is an empty array.
RUNE_SETTING_FLINT_WORKFLOWS_JSON- Configured workflow catalog. This is separate from a provider-supplied payload.
RUNE_PROCESS_POLICY_JSON- Allowlist for native process selectors used by bounded hooks. It is not arbitrary shell authority.
RUNE_CREDENTIAL_<NAME>- Operator credential input. A job value such as
$secret:CI_TOKENresolves only during sandbox process creation. Selected credentials are masked from raw and text process output before Scheme observes it. RUNE_HTTPS_ALLOWED_AUTHORITIES- Explicit outbound HTTPS authorities. Provider status settings do not bypass this allowlist.
Provider settings use RUNE_CREDENTIAL_<SERVICE>_WEBHOOK_SECRET, RUNE_CREDENTIAL_<SERVICE>_STATUS_TOKEN, and RUNE_SETTING_<SERVICE>_STATUS_AUTHORITY. Service prefixes are GITHUB, FORGEJO, and GITEA.
The operator-owned content store beneath .rune/native/content/ contains pinned actions/<40-character-commit>/action.yml, verified oci-layers/<source-key>/<layer>.tar, and assembled oci/<64-character-image-digest>/ roots. Rune confines metadata reads, verifies layer digests, publishes roots transactionally, and mounts selected content read-only. This is not a claim that Forge can emit an OCI artifact.
Versioned HTTP contract
The matched preview declares exactly POST /v1/flint, POST /hooks/github, POST /hooks/forgejo, and POST /hooks/gitea. HTTP is disabled in the checked-in runtime config. Hosting requires a deployed service and explicit local endpoint configuration.
For the matched candidate, the Flint operation request body uses operation and arguments. This is a read-only lookup example for an existing run, not a promise that a listener is active:
{
"operation": "flint.get_run",
"arguments": {"run_id": "an-existing-run-id"}
}The older baseline uses method and params with its older dispatch names. Those envelopes are not interchangeable. A version string alone cannot select the protocol. Inspect the matched implementation and active deployment.
The operation registry contains /v1/operations/... annotations, but direct requests to those paths returned 404 in evaluation. Those annotations are not advertised as callable HTTP routes here. Use the exact declared route and a matched envelope. Internal control methods are not a public bypass.
Webhook verification uses the exact body and provider signature header. GitHub uses x-hub-signature-256 and x-github-delivery. Forgejo uses x-forgejo-signature and x-forgejo-delivery. Gitea uses x-gitea-signature and x-gitea-delivery. Unknown mappings, invalid SHAs, or missing verification authority fail closed. The signature does not authorize arbitrary embedded workflows.
These routes do not implicitly configure TLS, public exposure, general operation authentication, or provider credentials. See Rune's body, concurrency, and route limits.
MCP registration and hosting limits
The candidate registry declares these operations. Registration documents policy; it is not proof of a deployable transport:
flint.run_workflow- A mutating tool taking
workflow. It validates, stores, and drives trusted work. flint.get_run- A read-only resource template using
flint://runs/{run_id}. flint.cancel_run- A persistent CI cancellation tool taking
run_id. flint.ci_health- A read-only health tool.
flint.ci_guidance- A prompt about safe inspection and cancellation.
The registry declares protocol version 2025-11-25, a default 30000 ms timeout, and a 65536-byte output bound. Library and fixture transport tests do not establish a current production MCP process entrypoint. That entrypoint is missing from the production CLI. There are no runnable MCP hosting instructions in this guide.
MCP request cancellation concerns the in-flight request. It does not persist CI cancellation. Use the domain cancellation action through an available, matched interface and inspect cleanup results.
Domain results and stable errors
Stored run states include queued, in_progress, success, failure, and cancelled. A replay gets a new run ID and a replay_of link. Logs and explanation refer to stored job outcomes. A queued replay still needs a worker.
Domain responses contain a result or an error object. Public operation registration lists -32602 for invalid arguments, -32004 for a missing run or unsuccessful cancellation lookup, and -32026 for a workflow execution contract failure. An unknown or disallowed operation uses -32601.
Graph validation uses -32020 for an unsupported schema version, -32021 for duplicate job IDs, -32022 for an unknown dependency, -32023 for a dependency cycle, and -32029 for an unsupported condition. Read the message and any location pointer before retrying.
HTTP status, the global CLI envelope, the defcli handler result, and the stored job status are separate layers. Inspect all applicable layers. A top-level success or HTTP 200 does not prove the jobs passed, the sandbox was cleaned, or provider status was published.