> ## Documentation Index > Fetch the complete documentation index at: https://cli-docs.relai.ai/llms.txt > Use this file to discover all available pages before exploring further. # init > Reference for relai init. `relai init` registers an agent project and generates simulator support. ```sh theme={"system"} relai init ``` `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](/quickstart#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 | Flag | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------- | | `--resume` | Continue the unfinished local init session for this repository. Restores the original options and progress. | | `--restart` | Discard the unfinished local init session and start initialization again. | | `--override-creds` | Prompt for project-specific RELAI API credentials instead of reusing user-level credentials. | | `--agent-target {TARGET}` | Register one discovered logical agent target. May be repeated. | 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: ```sh theme={"system"} relai init --approval-mode all ``` 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: ```sh theme={"system"} relai init --agent-target {target-a} --agent-target {target-b} ``` 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`](/cli/learning-env). * `.relai/evaluators/` for evaluators, from [`relai evaluator`](/cli/evaluator). * `.relai/benchmarks/` for benchmarks, from [`relai benchmark`](/cli/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](/cli/learning-env). 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 ```sh theme={"system"} git status --short relai init ``` ## 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. ```gitignore theme={"system"} # Keep local-only files out of RELAI context {local-only-directory}/ *.{local-extension} # Re-include one required file !{local-only-directory}/{required-file}.{extension} ``` `.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.