Skip to main content
relai init registers an agent project and generates simulator support.
relai init can take a while for larger or more complex agents because RELAI inspects the project and generates a simulator harness for it.

​
Before you run it

Run it from the root of a git-tracked agent repository. The project should satisfy the project requirements. Run relai setup first to configure machine-level RELAI credentials, or provide them when relai init prompts. When project credentials already exist in .relai/config.toml, relai init reuses them without asking for them again. Otherwise, when user-level credentials exist in ~/.relai/config.toml, relai init reuses them for the project without prompting. Use --override-creds when this project should use different RELAI API credentials.

​
Options

Interactive runs may ask for RELAI credentials, permission to inspect untracked project files or install dependencies, agent metadata, mock policies, and whether to commit the RELAI-managed files. Full simulator validation must pass before RELAI registers agent targets.

​
How initialization works

relai init uses one agentic workflow for every supported language. The CLI creates a trusted language-specific seed, then the init agent inspects selected repository files, reports its resolved dependencies and logical agent targets, adapts the seed, and validates the simulator locally. There is no legacy generation path or feature flag. Common and language-specific simulator guidance is compiled into the CLI. The agent can resolve dependencies through the selected Python, TypeScript, or Go environment and inspect bounded declarations or source for named integration points. It generates a project-owned adapter with explicit, behaviorally verified capabilities; the RELAI SDK does not infer third-party framework hooks. Repository and dependency reads remain bounded, sensitive paths stay unavailable, and external local dependency roots require approval.

​
Approval modes

By default, init prompts for approval in an interactive terminal and pauses with an action-required checkpoint when stdin is non-interactive. Use --approval-mode require to request that pausing behavior explicitly, or --approval-mode all to automatically approve every bounded action that would otherwise ask for confirmation:
Approve-all is intended for trusted automation such as isolated compatibility fixtures. It does not override sensitive-path protections, explicit permission deny rules, path and symlink validation, or actions the init policy rejects. Use [permissions].profile = "workspace" separately when the init agent must be allowed to edit application files. --approval-mode prompt requires an interactive terminal. After validation, RELAI asks you to select any discovered logical targets, records the selected target-to-agent mappings, and registers them with the backend. In an interactive terminal, it can then offer to commit the changed .gitignore and .relai/ files. In a non-interactive terminal, it prints the equivalent commit command instead.

​
Pause, resume, or restart

Initialization checkpoints its progress in .relai/init-session.json whenever it needs an answer, approval, an external action, or recovery from an interruption. Run relai init --resume to continue the same session. Resume restores earlier model and tool progress, permission decisions, validation progress, selected options, and completed phases; it cannot be combined with --override-creds or --agent-target. Run relai init --restart to discard an unfinished checkpoint and begin again. If an unfinished session exists, interactive init offers to resume, restart, or cancel; non-interactive init requires one of those flags. A completed init removes the checkpoint. Each session also writes a metadata-only diagnostic record under .relai/runs/. It contains action names, statuses, request IDs, timings, and token usage, but not prompts, source bodies, diffs, or raw command output.

​
Agent targets

Repositories with several logical agents can register each one as a named agent target. During interactive initialization, RELAI shows the discovered targets with their code entrypoint and, when available, runtime selector. Use Space to toggle each target and Enter to confirm the selection. RELAI creates one backend agent for every selected target and records the target-to-agent mapping in .relai/config.toml. To select targets non-interactively, repeat --agent-target with discovered target names:
When a project has multiple registered targets, commands that create learning environments, benchmarks, or evaluators let interactive users choose one target at a time. In non-interactive runs, pass --agent-target {target} explicitly.

​
What it creates

  • project registration with the RELAI backend.
  • simulator files under .relai/simulator/.
  • runtime and mock manifests.
  • .relai/learning-env-context.json.
  • .relai/simulator.env.example.
  • a temporary local init checkpoint while initialization is paused or in progress; it is removed after completion.
  • a metadata-only local diagnostic record under .relai/runs/.
  • an interactive offer, or non-interactive instructions, to commit changed .gitignore and .relai/ files.
As you use RELAI, the other objects live alongside these under .relai/, each created by its own command:
  • .relai/learning-envs/ for learning environments, from relai learning-env.
  • .relai/evaluators/ for evaluators, from relai evaluator.
  • .relai/benchmarks/ for benchmarks, from relai benchmark.
  • .relai/runs/ for simulation and optimizer run artifacts.

​
Mocking tools and components

During interactive initialization, RELAI may list agent tools, callable functions, or component dependencies that the generated simulator can replace with mocks. For each replaceable target, relai init shows the target, the kind of target, RELAI’s recommendation, and the reason for that recommendation, then asks whether to mock it:
  • Always records mock. Learning environments must provide a mock for that target.
  • Never records do_not_mock. Learning environments must let that target run normally.
  • Depends records any. Each learning environment can decide whether that target should be mocked.
Use Always for calls that make simulations slow, flaky, expensive, unsafe, or dependent on external state, such as network lookups, writes to third-party systems, or calls that need production credentials. Use Never when the component is part of the behavior you want RELAI to exercise directly, such as local deterministic logic or a component-specific learning environment target. Use Depends when the right choice varies by scenario. Some targets are marked cannot_mock. RELAI records those decisions without asking because the generated simulator cannot reliably replace that target, for example a hosted tool that only runs remotely. These choices record whether a target may be mocked, not how. To control the mock’s behavior in a given scenario — a tool that always succeeds, or one that returns a specific error the agent should handle — describe it in the --prompt or --feedback when you create the learning environment. The final choices are written to .relai/mock-manifest.json and are checked when you create or upload learning environments. If a component requires one of its dependencies to be mocked, RELAI will reject Never for that target. If a component needs a target to run live, RELAI will reject Always.

​
Example

​
Controlling project inputs with .relaiignore

Add a root-level .relaiignore file when some project files should stay out of agentic init model context, other RELAI generation inputs, and optimizer worktrees. It uses familiar .gitignore-style patterns, including comments, globs, directory patterns, anchored paths, and negation. Replace the placeholder names below with project-specific paths.
.relaiignore applies only to project files. RELAI-managed .relai/ runtime state is outside its scope, so required simulator harness files, manifests, learning environments, benchmarks, and run metadata continue to use RELAI’s built-in rules. The .relaiignore file itself is also treated as a local control file and is not sent as backend context. If a command explicitly asks for an ignored project file, RELAI fails clearly instead of silently bypassing the boundary. For example, registering a benchmark with an ignored --csv, creating a learning environment from an ignored --log-file, or optimizing with an ignored runtime env file will report that the path is excluded by .relaiignore. .relaiignore is independent of .gitignore: git can still track files that RELAI excludes from backend inputs and optimizer worktrees.

​
Common failures

  • not running inside a git repository.
  • missing RELAI credentials.
  • missing required local tools.
  • init model or local validation failure.
  • an action that requires approval in a non-interactive terminal.
  • an unfinished init session; resume it with relai init --resume or discard it with relai init --restart.
  • missing runtime environment values required by the smoke test.
  • tracked generated paths already have local changes.
  • the project cannot expose a runnable local simulator surface.
This command writes files. Review generated files before committing them.