CLI Reference

← ratatouille.dev

The rat CLI is the primary operator interface for Ratatouille. It handles fleet creation, agent enrollment, live status monitoring, and cryptographic evidence export.

Install:

pip install ratatouille

Configuration: rat stores its API endpoint in ~/.rat/config.json. Set it once with rat connect.

---

rat connect

rat connect <url>

Configure which Ratatouille Core instance to connect to. Tests the connection before saving.

rat connect https://your-core-instance
# or interactively:
rat connect
# API endpoint [http://localhost:8001]:

The configured URL is used by all subsequent commands. Stored at ~/.rat/config.json.

---

rat init

rat init

Create a new fleet (policy group) and generate a baseline enrollment token. Prompts for a fleet name, then waits for the first agent to enroll.

What it does:

1. Creates the policy group on the Ratatouille Core
2. Generates a one-time baseline enrollment token (esp_b_...)
3. Prints enrollment commands for three methods: rat enroll, Ansible, and cloud-init
4. Polls until the first agent checks in, then confirms enrollment

Output includes enrollment commands for:

# rat CLI (run on the target machine)
rat enroll esp_b_<token> --server https://your-core-instance

# Ansible
- name: Enroll agent
  shell: pip install ratatouille && rat enroll esp_b_<token> --server https://your-core-instance

# cloud-init
runcmd:
  - pip install ratatouille && rat enroll esp_b_<token> --server https://your-core-instance

The first machine enrolled with a baseline token becomes the reference device — its IMA measurement log is used to generate the runtime policy for the group.

---

rat enroll

rat enroll <token> [--server <url>]

Enroll this machine into a fleet. Run on the agent device, not the operator machine.

Argument	Description
<token>	Enrollment token from rat init (esp_b_... for baseline, esp_... for standard)
--server, -s	Override the API URL for this enrollment (also saves to config)

What it does:

1. Validates the token against the Ratatouille Core
2. Retrieves the Keylime registrar/verifier addresses and policy group assignment
3. Runs the bundled install script (requires sudo)
4. The install script installs the Keylime Rust agent, configures it, and initiates the TPM credential activation ceremony

The Keylime agent must be reachable by the Ratatouille verifier over the network after enrollment.

---

rat status

rat status [--watch] [--group <group-id>]

Show the current attestation status of all enrolled agents.

Flag	Description
--watch, -w	Refresh every 10 seconds
--group, -g	Filter output to a specific policy group

Status values:

Status	Meaning
ACTIVE	Agent is enrolled and attesting. Last quote verified against policy.
PROVISIONING	Agent enrolled, awaiting first successful attestation cycle.
FAILED	Attestation failed — IMA log entry not in policy or PCR mismatch.
UNKNOWN	Verifier cannot reach the agent or no recent quote.

Example output:

  ━━ Fleet Status  http://localhost:8001

   ●  prod-node-01.fleet.internal   prod-fleet   ACTIVE     PCR[7]+[10]   12s ago
   ●  prod-node-02.fleet.internal   prod-fleet   ACTIVE     PCR[7]+[10]   8s ago
   ✗  edge-device-07.iot.internal   edge-fleet   FAILED     —             26m ago

---

rat evidence

rat evidence <hostname|uuid> [--export <path>]

Show the full cryptographic proof chain for a single agent, with the verification command for each link.

Argument	Description
<hostname|uuid>	Agent hostname or UUID
--export, -e	Write a JSON evidence report to the specified file path

The proof chain displayed:

Step	What it proves	How to verify independently
1. TPM Hardware Identity	EK certificate is manufacturer-issued and signed by vendor CA	openssl verify -CAfile <ek_ca.pem> <ek_cert.pem>
2. TPM Quote Signature	Fresh-nonce hardware quote signed by the Attestation Key	tpm2_checkquote --public ak.pub --message quote.msg --signature quote.sig
3. PCR[7] Secure Boot	Secure Boot was enabled and DB/DBX/PK/KEK set is unchanged	sudo tpm2_pcrread sha256:7
4. PCR[10] IMA Runtime	Every binary that executed since boot is in this log, anchored to hardware	sudo cat /sys/kernel/security/ima/ascii_runtime_measurements
5. Runtime Policy	Policy is Sigstore-signed by an authorized identity	cosign verify-blob --bundle artifact.sigstore.json runtime_policy.json
6. Rekor Transparency Log	Policy signing event is publicly logged, append-only, independently auditable	rekor-cli get --log-index <id>

JSON export (--export report.json) produces a structured evidence package suitable for auditor submission. It includes all chain metadata and the verification commands for each step.