CLI

Getting started

The jio CLI is the local control surface for Jio Core. It validates policy, plans an environment without contacting a worker, starts bounded sessions explicitly, and returns structured results suitable for both people and agents.

Jio Core is currently pre-release. Build the CLI from the source checkout:

cargo build --release --bin jio

Place target/release/jio on your PATH if you want to use the shorter commands shown below.

Current runnable trust mode

The current acceptance path uses trusted-host and is explicitly unattested. The host and its operator can read workspace and tool plaintext. confidential fails closed as unavailable in this iteration; Jio never downgrades it automatically.

First-use workflow

Create a local identity once

jio identity init --path .jio/identity.json

Reuse an existing identity. The command refuses to replace one, and automation should never delete it to make setup pass.

Add a reviewed policy

.jio/jio.toml

version = 1
trust = "trusted-host"
endpoint = "http://127.0.0.1:7443/mcp"
workspace = "."
allow_unattested = true

This example is for the local trusted-host acceptance path. Use the endpoint, workspace, and trust mode that your operator has explicitly provided.

Validate locally

jio doctor --config .jio/jio.toml \
  --identity .jio/identity.json --json

doctor checks local readiness and security posture without allocating compute or sending the workspace.

Review the plan

jio plan --config .jio/jio.toml \
  --identity .jio/identity.json --json

Inspect the environment ID, resolved toolchains, recommended profile, TTL, trust, attestation, egress, and cost metadata before continuing.

Start and run

jio session start --config .jio/jio.toml \
  --identity .jio/identity.json --json

jio run --config .jio/jio.toml \
  --identity .jio/identity.json --json -- cargo test

Core workflow

Review remote changes before applying them locally:

jio diff --config .jio/jio.toml \
  --identity .jio/identity.json --json

jio sync --config .jio/jio.toml \
  --identity .jio/identity.json --json

jio session stop --config .jio/jio.toml \
  --identity .jio/identity.json --json

Ordinary traffic does not renew a lease. Extend it explicitly with jio session renew --ttl-seconds <seconds> ....

Commands

The current jio --help exposes these public command groups:

Command	Purpose
`jio identity init\|show`	Create a non-replacing Ed25519 identity or print its public key
`jio doctor`	Validate local configuration and report security posture
`jio plan`	Resolve environment and compute policy without contacting a worker
`jio session start\|status\|renew\|stop`	Manage the renewable remote session
`jio run`	Run one bounded foreground command remotely
`jio diff`	Return the remote workspace delta
`jio sync`	Apply the reviewed remote delta locally after conflict checks
`jio artifact export\|pull`	Export and retrieve content-addressed artifacts
`jio secret set\|list\|delete`	Manage session secrets without placing values in arguments
`jio service start\|status\|logs\|stop`	Operate named supervised private services
`jio runtime install\|list`	Install and inspect immutable local runtime packs
`jio mcp`	Run the stdio bridge or install project-scoped Codex configuration

Use jio <command> --help for the flags accepted by a specific command.

Common operations

Export only the remote paths you intend to publish, then pull the resulting artifact by ID:

jio artifact export --config .jio/jio.toml \
  --identity .jio/identity.json --json dist

jio artifact pull --config .jio/jio.toml \
  --identity .jio/identity.json --json <artifact-id>

Inspect destination conflicts before adding --overwrite.

Policy flags

Prefer a reviewed .jio/jio.toml. For trusted-host experiments, the CLI also accepts the complete direct policy:

jio doctor \
  --endpoint http://127.0.0.1:7443/mcp \
  --workspace . \
  --trust trusted-host \
  --allow-unattested \
  --identity .jio/identity.json \
  --json

Direct flags currently support trusted-host only. Confidential mode requires a policy file. Project MCP installation also requires an existing policy file; it does not persist direct endpoint or trust choices for you.

Command networking defaults to --network deny. Enable --network packages only when the reviewed local and remote policy permits the bounded package destinations required by the task.

Structured results

Use --json for automation and agents. Failures return a typed envelope with an error code, details, and a retryability signal:

{
  "error": {
    "code": "approval_required",
    "details": {},
    "retryable": false
  }
}

Handle the reported code narrowly. Do not change trust mode, delete local authority, or broaden policy merely to make a command succeed.

After the CLI path works, continue with the Jio Compute skill or install the project MCP integration.

On this page