SDKs and CLI

Use the Keiro package when you want saved credentials and a prompt-first eb1 client. Use an OpenAI-compatible SDK when you are migrating existing application code. Use curl when you need to inspect the raw HTTP contract.

On this page 1 of 6

For client timeout and retry settings, see Long requests.

Keiro Python package and CLI#

The keiro package needs Python 3.11, 3.12, or 3.13. It does not install on Python 3.14 yet. Check your version with python3 --version. If it prints 3.14, install Python 3.13 (on macOS with Homebrew: brew install python@3.13) and use python3.13 in place of python3 in the first command below.

Install the package in a virtual environment, then run interactive setup:

Configure Keiro CLI Shell
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade keiro
keiro setup

The Codex setup installs a different command that is also named keiro. Run keiro --version to see which one answers: this package prints a line that starts with keiro; the Codex launcher prints the Codex version. While this virtual environment is active, its keiro comes first on your PATH. Run deactivate before you start Codex with keiro.

Setup prompts for the API key, validates it, stores credential metadata in ~/.keiro/credentials, and stores secret bytes in owner-only files under ~/.keiro/secrets/. Later CLI and native-client calls use the saved endpoint and credential.

Run a one-shot prompt:

Run in the terminal Shell
keiro "Explain when to use eb1-preview in two bullets."

Adaptive preview models offer hosted web search by default and leave the decision to the model (tool_choice: "auto"). Use --no-search for a one-shot opt-out, or /search to toggle it in the REPL. Turning search on can change which models are available for a request; use --no-search if a request must run without it.

Or use the native Python facade:

Run a Python request Python
from keiro import models

print(models("eb1-preview", "Explain when to use eb1-preview in two bullets."))

The package does not discover a raw API key from a runtime environment variable. Run keiro setup again to change saved credentials. keiro setup asks for the key at a terminal prompt; for scripts and CI, use an OpenAI-compatible SDK with a key file, as shown below.

List the models available to the saved credential:

Run in the terminal Shell
keiro models

To remove the package and its saved credentials:

Run in the terminal Shell
python3 -m pip uninstall keiro
rm -rf ~/.keiro

OpenAI-compatible Python#

Install the SDK:

Install with pip Shell
python3 -m pip install --upgrade openai

Prompt for the key and pass it directly to the client:

Run a Python request Python
from getpass import getpass

from openai import OpenAI

client = OpenAI(
    base_url="https://api.keirolabs.ai/v1",
    api_key=getpass("Keiro API key: "),
)

response = client.responses.create(
    model="eb1-preview",
    input="Say hello in one sentence.",
)

print(response.output_text)

Use this pattern for one-off local scripts. Production services should resolve the key from their approved secret manager and pass it to the SDK constructor.

For scripts, CI jobs, and other runs with no person at a terminal, read the key from a file that your secret manager writes. KEIRO_KEY_FILE holds the file's path, not the key:

Run a Python request Python
import os
from pathlib import Path

from openai import OpenAI

key_path = os.environ.get("KEIRO_KEY_FILE")
if not key_path:
    raise SystemExit("KEIRO_KEY_FILE must point to a protected secret file")

client = OpenAI(
    base_url="https://api.keirolabs.ai/v1",
    api_key=Path(key_path).read_text(encoding="utf-8").strip(),
)

response = client.responses.create(
    model="eb1-preview",
    input="Say hello in one sentence.",
)

print(response.output_text)

Make the key file readable only by the account that runs the job (chmod 600), and do not commit it.

Generic OpenAI-compatible calls remain explicit: prompt text such as “search the web” does not declare a tool. To offer hosted search, include tools=[{"type": "web_search"}] and tool_choice="auto"; omit the tool (or use the surface's explicit none choice where supported) to opt out. This preserves caller control for compatibility and privacy, while the first-party Keiro CLI and Console apply their documented default themselves.

OpenAI-compatible JavaScript#

Install the SDK and enable ES modules — type=module turns on import syntax and top-level await for the sample below:

Install with npm Shell
npm install openai
npm pkg set type=module

Save the sample as hello.mjs and run it with node hello.mjs.

Point KEIRO_KEY_FILE at a secret file provisioned by your credential manager. The environment value is a non-secret path, not the key itself:

Run a JavaScript request JavaScript
import fs from "node:fs";
import OpenAI from "openai";

const keyPath = process.env.KEIRO_KEY_FILE;
if (!keyPath) {
  throw new Error("KEIRO_KEY_FILE must point to a protected secret file");
}

const client = new OpenAI({
  baseURL: "https://api.keirolabs.ai/v1",
  apiKey: fs.readFileSync(keyPath, "utf8").trim(),
});

const response = await client.responses.create({
  model: "eb1-preview",
  input: "Say hello in one sentence.",
});

console.log(response.output_text);

Protect the secret file with the operating system and your deployment platform's secret controls. Do not commit it or place raw secret bytes in a shared .env file.

Curl#

Curl is useful for checking headers and raw response shapes:

Run a curl request Shell
printf 'Keiro API key: '
IFS= read -rs KEIRO_BEARER
printf '\n'

curl -sS https://api.keirolabs.ai/v1/responses \
  -H "Content-Type: application/json" \
  -d '{"model":"eb1-preview","input":"Say hello in one sentence."}' \
  -H @- <<<"Authorization: Bearer $KEIRO_BEARER"

The prompt works in both bash and zsh, and -H @- (curl 7.55 or newer) reads the Authorization header from stdin so the secret never appears in the process argument list.

Local chat UI#

After keiro setup, run:

Run in the terminal Shell
keiro gui

The command starts a local browser chat UI connected to the saved public endpoint and key. It is for chat exploration, not organization, billing, or API-key administration.

Search Keiro docs

Start typing to search pages and sections.

Start typing to search pages and sections.

Documentation

Console