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
- Run
cordierite session --json. The response includesdata.sessions(each entry hassession_id, status, endpoint info, etc.). Ifsessionsis empty, no Cordierite host is registered for this machine (for this registry). - If you need a new session for a device, follow Establish a session below. Record
host.session_idfrom the host JSON—you must pass it totoolsandinvoke. - After the user opens the deep link on the device and the app connects, confirm with
cordierite session --session-id <session_id> --jsonuntildata.selectedreflects an active connection (or re-checksession --jsonand infer from the listed session). cordierite tools --session-id <session_id> --json— list tools registered in the app.cordierite tools --session-id <session_id> <tool-name> --json— inspect one tool’s input/output schema before calling it.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 cert, key, and app URL scheme as the project (see Setup if you are wiring Cordierite into an app). If the default listen port is in use, add --port <port>.
cordierite host --tls-cert /path/to/cert.pem --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-idtotools/invoke/session --session-id.
Then:
- 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.
- Or open it yourself when you know the target (e.g. iOS Simulator
xcrun simctl openurl booted '<url>', Android viaadb, 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",
input_schema: echoInput,
output_schema: echoOutput,
},
async (args) => ({ echoed: args.value }),
);
Notes
- Use
--jsonfor structured CLI output in agent flows. toolsandinvokealways require--session-id(the value fromhost.session_idorsessions[].session_id).- Prefer
cordierite session --jsonfirst rather than assuming a session exists. - If
sessionsis empty ortools/invokefail with connection or session errors, establish a session (host running, deep link opened on the correct device). - If the app registers no tools,
cordierite toolsreturns an empty list. - You may run multiple
cordierite hostprocesses (e.g. different--portfor different devices); use thesession_idthat belongs to the host you care about.
Setup
For project integration guidance, see setup.md.