# apigenie init

Source: https://apigenie.pl/docs/reference/cli/init
Part of the reference of [apigenie](https://apigenie.pl/docs/reference/cli.md).
Its other pages: [bundle](https://apigenie.pl/docs/reference/cli/bundle.md), [changelog](https://apigenie.pl/docs/reference/cli/changelog.md), [config](https://apigenie.pl/docs/reference/cli/config.md), [convert](https://apigenie.pl/docs/reference/cli/convert.md), [credits](https://apigenie.pl/docs/reference/cli/credits.md), [diff](https://apigenie.pl/docs/reference/cli/diff.md), [evolve](https://apigenie.pl/docs/reference/cli/evolve.md), [format](https://apigenie.pl/docs/reference/cli/format.md), [i18n](https://apigenie.pl/docs/reference/cli/i18n.md), [license](https://apigenie.pl/docs/reference/cli/license.md), [lint](https://apigenie.pl/docs/reference/cli/lint.md), [overlay](https://apigenie.pl/docs/reference/cli/overlay.md), [test](https://apigenie.pl/docs/reference/cli/test.md).

Sets a repository up for API Genie and for coding agents: writes `apigenie.yaml` with the lint
rules of the API descriptions it finds, and adds the section that tells coding agents how to check
them to `AGENTS.md`.

## Usage

```sh
apigenie init [DIR] [--ruleset recommended|strict|all] [--agents-file FILE] [--no-agents] [--dry-run] [--json]
```

```sh
apigenie init
apigenie init --ruleset strict --agents-file CLAUDE.md
```

## Description

`init` works on the repository that holds `DIR` (the current directory by default): the
directory of the configuration file the other commands would read there, else the root of its
git repository, or `DIR` itself outside git. It finds the API descriptions in it as
[`apigenie-catalog`](/docs/reference/catalog) does (the files git lists, OpenAPI, Swagger 2.0,
AsyncAPI, Protobuf and GraphQL), lists them, and writes two files at the root:

- **`apigenie.yaml`**, unless the repository has a
  [configuration file](/docs/reference/cli/configuration) already, which is kept as it is. The new
  file has the linter extend `--ruleset` (`recommended` by default) for OpenAPI and for each other
  family found, and `format` and `diff` their recommended settings. It names its JSON Schema for
  editors.
- **The section "API descriptions"** for coding agents, the one the guide
  [Work with AI agents](/docs/guides/work-with-ai-agents) shows: in `AGENTS.md`, or the file of
  `--agents-file` (`CLAUDE.md`, `.github/copilot-instructions.md`, ...). A new file gets the
  section; a file without it gets it appended; a file with a line `## API descriptions` is kept.
  The section takes the file's line endings. `--no-agents` leaves the file alone.

Running `init` again changes nothing. `--dry-run` prints what it would write and writes nothing.
Commit both files, so that every agent and every CI run use the same rules.

## Options

| Option | Description |
| ------ | ----------- |
| `--ruleset NAME` | `recommended` (default), `strict` or `all`: the ruleset the linter extends for every family. |
| `--agents-file FILE` | The instructions file of the coding agents, relative to the repository and inside it (default `AGENTS.md`). |
| `--no-agents` | Write no instructions for coding agents. |
| `--dry-run` | Print what would be written, and write nothing. |
| `--git PATH` | The git program (default `git`). |
| `--json` | Print the report ([`apigenie-init-report.json`](https://apigenie.pl/schemas/apigenie-init-report.json)): the root, each file with its outcome (`created`, `updated`, `kept`, `skipped`) and the API descriptions found. |

## Exit status

| Status | Meaning |
| ------ | ------- |
| 0 | The repository is set up (or, with `--dry-run`, would be). |
| 2 | A usage error, a directory that doesn't exist, or git failed. |

These are the statuses of every command ([exit status](/docs/reference/cli#exit-status)).

## See also

- [Configuration](/docs/reference/cli/configuration): the sections of `apigenie.yaml`.
- [Work with AI agents](/docs/guides/work-with-ai-agents): what the section asks of an agent.
- [`apigenie-catalog init`](/docs/reference/catalog): the `catalog` section of `apigenie.yaml`.
