Cordierite

Cordierite

Cordierite is a CLI and host workflow for connecting to a Cordierite-enabled React Native app, discovering its registered tools, invoking those tools from the terminal, and ending the session cleanly after use.

Agent workflow

1. Run `cordierite session --json`. The response includes `data.sessions` (each entry has `session_id`, status, endpoint info, etc.). If `sessions` is empty, no Cordierite host is registered for this machine (for this registry). 2. If you need a new session for a device, follow Establish a session below. Record `host.session_id` from the host JSON—you must pass it to `tools` and `invoke`. 3. After the user opens the deep link on the device and the app connects, confirm with `cordierite session --session-id <session_id> --json` until `data.selected` reflects an active connection (or re-check `session --json` and infer from the listed session). 4. `cordierite tools --session-id <session_id> --json` — list tools registered in the app. 5. `cordierite tools --session-id <session_id> <tool-name> --json` — inspect one tool’s input/output schema before calling it. 6. `cordierite invoke --session-id <session_id> <tool-name> --input '{"key":"value"}' --json` — invoke the tool with JSON args.

Establish a session

Start the host with `--json` using the same TLS key and app URL scheme as the project (see Setup if you are wiring Cordierite into an app). The CLI generates the host certificate automatically from the resolved local IP. If the project does not already have a trusted host key, create one first with `cordierite keygen` in an interactive terminal and add the printed fingerprint to the app’s `cliPins`. If the default listen port is in use, add `--port <port>`.

cordierite host --tls-key /path/to/key.pem --scheme myapp --json

Run `cordierite host` in the background. It blocks; keep the foreground shell free for session, tools, and invoke.

From the host JSON output, use at least:

• `host.deep_link` — full URL (e.g. myapp:///?cordierite=…) for the app to open.
• `host.session_id` — pass this as `--session-id` to `tools` / `invoke` / `session --session-id`.

Then:

1. Give the user the deep link (or QR from interactive host UI on a TTY) so they can open it on a device or simulator. 2. Or open it yourself when you know the target (e.g. iOS Simulator xcrun simctl openurl booted '<url>', Android via adb, or device automation skills).

After the app opens the link and claims the session, poll `cordierite session --session-id <session_id> --json` (or `session --json`) until the session is active.

Terminate the connection

When the user wants to disconnect or stop Cordierite for that session: stop the matching background `cordierite host` process (end the job, SIGTERM, etc.). That tears down the host and the session. If several hosts run (e.g. different `--port`), stop the one that corresponds to the `session_id` you were using.

Declaring tools

The app must register tools before `cordierite tools` / `cordierite invoke` can do anything useful. Define schemas with Zod and register with `registerTool`:

import { registerTool } from "@cordierite/react-native";
import { z } from "zod";

const echoInput = z.object({
  value: z.unknown(),
});

const echoOutput = z.object({
  echoed: z.unknown(),
});

registerTool(
  {
    name: "echo",
    description: "Return the input unchanged",
    inputSchema: echoInput,
    outputSchema: echoOutput,
    handler: async (args) => ({ echoed: args.value }),
  },
);

Notes

• Use `--json` for structured CLI output in agent flows.
• `cordierite keygen` is the normal setup command for new host keys. It is interactive-only in v1: it writes a PEM private key and prints the exact `sha256/...` fingerprint the app should trust.
• `tools` and `invoke` always require `--session-id` (the value from `host.session_id` or `sessions[].session_id`).
• Prefer `cordierite session --json` first rather than assuming a session exists.
• If `sessions` is empty or `tools` / `invoke` fail with connection or session errors, establish a session (host running, deep link opened on the correct device).
• If the app registers no tools, `cordierite tools` returns an empty list.
• You may run multiple `cordierite host` processes (e.g. different `--port` for different devices); use the `session_id` that belongs to the host you care about.

Setup

For project integration guidance, see setup.md.

Cordierite setup

Use this file when the task is to add Cordierite to a new React Native project.

Shared requirements

1. Install cordierite where the operator or agent will run the CLI. 2. Install @cordierite/react-native in the app. 3. Register the app tools you want Cordierite to expose. 4. Configure deep linking so the OS can open your app with the Cordierite bootstrap URL. Importing @cordierite/react-native registers listeners (via React Native Linking) that parse bootstrap URLs and call connect automatically; you do not need a manual Linking handler for the default flow. 5. Generate or provide a TLS private key for the host. For a new setup, prefer running cordierite keygen in an interactive terminal. 6. Add the matching sha256/... SPKI pin to the app configuration. Use the fingerprint printed by cordierite keygen. The CLI generates the leaf certificate automatically from that key and the resolved host IP. 7. Optional: use addCordieriteErrorListener to observe bootstrap parse failures or failed auto-connect attempts. 8. Advanced: use the exported cordieriteClient for manual connect, extra event listeners, or tests.

Expo

1. Add @cordierite/react-native to the app dependencies. 2. Add the Cordierite Expo config plugin to the Expo config. 3. Configure at least cliPins; optionally configure the private-LAN-only restriction if the project wants it. 4. Make sure the app scheme used by the project matches the scheme the CLI will pass to cordierite host --scheme .... 5. Run prebuild or rebuild the native project so the native config is applied. 6. Use a development build. Expo Go is not enough.

Bare React Native

1. Add @cordierite/react-native to the app dependencies. 2. Run the normal native dependency installation steps for the project. 3. Add the trusted host pins to native configuration on iOS and Android. 4. Add the optional private-LAN-only setting only if the project wants that restriction. 5. Configure URL schemes / intent filters so bootstrap links ({scheme}:///?cordierite=…) open your app. 6. Rebuild the native app after the configuration changes.

Final check

• The CLI host has a readable private key
• The app trusts the host's current pin
• The app has at least one registered tool
• The app scheme matches the host --scheme value