CLI and agent.toml

The CLI validates, creates, applies, and exports API-only Agents. It does not run Responses or manage Runtime infrastructure.

Install

Node.js 22 or later and pnpm are required.

pnpm add --global https://github.com/ReByteAI/rebyte-agent-sdk/releases/latest/download/rebyte-cli.tgz
rebyte --version

The package is a public, token-free GitHub Release asset. It is not installed from an npm registry.

Create agent.toml

name = "research-assistant"
description = "Research with source-backed answers"
llm = "deepseek-v4-pro"
max_steps = 32

prompt = """
Be concise and cite the evidence you use.
"""

capabilities = [
  "web_search_&_browse",
  "sandbox",
  "skills",
  "composio:github",
  "custom:550e8400-e29b-41d4-a716-446655440000"
]

[[skills]]
repo = "rebyteai/skills"
path = "research/deep-research"

Manifest schema

Unknown fields are rejected.

Field	Required	Initial value	Constraint
name	Yes	—	Trimmed string, 1–100 characters.
description	No	Not set	Trimmed string, up to 500 characters.
llm	No	deepseek-v4-pro	One of the supported Agent model IDs.
max_steps	No	32	Integer from 1 through 128.
prompt	No	Empty	Inline instructions, up to 100,000 characters.
prompt_file	No	—	UTF-8 instructions loaded relative to agent.toml.
capabilities	No	Seven default internal tools	Up to 64 unique capability strings.
skills	No	Empty	Up to 128 unique repo and path pairs.

prompt and prompt_file are mutually exclusive. A loaded prompt_file may not exceed 100,000 characters.

Use a model ID listed in Agents.

Capability strings map to API tool references:

web_search_&_browse → {"kind":"internal","name":"web_search_&_browse"}
composio:github     → {"kind":"composio","toolkit":"github"}
custom:<uuid>       → {"kind":"custom","serverId":"<uuid>"}

Every internal name listed in Tools and Skills is accepted. Composio names must be non-empty and at most 300 characters; custom server IDs must be UUIDs.

Each Skill has this shape:

[[skills]]
repo = "owner/repository"
path = "skills/research"

repo omits .git. path is a repository-relative directory and does not end in SKILL.md.

Commands

rebyte agent validate [-f agent.toml]
rebyte agent create [-f agent.toml]
rebyte agent apply <agent-id> [-f agent.toml]
rebyte agent export <agent-id> [-o agent.toml] [--force]

Validate

rebyte agent validate -f agent.toml

Validation is local and needs no API key. It parses TOML, validates every field, and resolves prompt_file.

Create and apply

export REBYTE_API_KEY="rbk_..."
rebyte agent create -f agent.toml
rebyte agent apply "$REBYTE_AGENT_ID" -f agent.toml

apply sends the complete resolved manifest. Omitting skills or capabilities applies their documented initial values; it is not a partial patch.

Export

rebyte agent export "$REBYTE_AGENT_ID" -o agent.toml

Export emits canonical TOML with inline prompt. It cannot preserve comments, formatting, or the original prompt_file path. It refuses to replace an existing file unless --force is supplied. Omit -o or pass -o - for stdout.

Select an environment

rebyte agent create -f agent.toml --env dev
rebyte agent create -f agent.toml --env test
rebyte agent create -f agent.toml --env prod
rebyte agent create -f agent.toml --base-url https://example.internal

Resolution order:

1. --base-url.
2. REBYTE_BASE_URL when --env is absent.
3. --env, otherwise REBYTE_ENV, otherwise prod.

Environment	Base URL
dev	REBYTE_DEV_BASE_URL, otherwise http://localhost:3332.
test	REBYTE_TEST_BASE_URL; required.
prod	https://api.rebyte.ai.

--api-key overrides REBYTE_API_KEY.

Agents created by the CLI belong to the API key's organization and do not appear in the Workspace Agent UI. Execute them through /v1/responses.