arkyn
ChangelogGuides
docs / commands / init

arkyn init --agents

Creates the AGENTS.md file in the current directory if it doesn't exist yet, or updates it in place if it does, linking to the AGENTS.md reference docs shipped inside your installed @arkyn/* packages.

Usage

bash

npx @arkyn/cli init --agents
init currently requires the --agents flag; it's the only flag init supports today, the command is structured to accept more in the future.

What it does

  1. Reads the package.json in the current working directory.
  2. Collects every @arkyn/* package listed under dependencies or devDependencies (the union of both, deduplicated, sorted alphabetically). @arkyn/cli itself is always excluded from this list, even if it appears as a dependency.
  3. For each package found, checks whether node_modules/@arkyn/<package>/AGENTS.md exists on disk.
  4. Writes (or updates) a block delimited by <!-- arkyn:agents:start --> and <!-- arkyn:agents:end --> markers inside the project's AGENTS.md, containing a markdown link to each AGENTS.md that was found.
If no @arkyn/* package is installed, or none of the installed ones ship an AGENTS.md yet (older package versions), the command prints the reason to the terminal and doesn't modify any file.

Example output

bash

$ npx @arkyn/cli init --agents
Updated AGENTS.md with docs for: @arkyn/components, @arkyn/server

Generated block

md

<!-- arkyn:agents:start -->
## Arkyn


Consult each installed Arkyn package's AGENTS.md before using its
components or utilities:


- [@arkyn/components](node_modules/@arkyn/components/AGENTS.md)
- [@arkyn/server](node_modules/@arkyn/server/AGENTS.md)
<!-- arkyn:agents:end -->

Guarantees

  • Idempotent: running the command again replaces the existing arkyn:agents:start/arkyn:agents:end block in place, it's never duplicated.
  • Non-destructive: the command never touches anything outside its own marked block. Any manual notes you've already written in AGENTS.md are preserved.
  • Created from scratch when missing: if AGENTS.md doesn't exist yet, it's created containing just the generated block.
  • Appended when markers are missing: if AGENTS.md exists but doesn't have the markers yet, the block is appended to the end of the file (respecting whether the file already ends with a newline or not).

Errors

Missing --agents flag: running arkyn init without --agents prints an error and the help message, and exits with code 1.

bash

$ npx @arkyn/cli init
arkyn init requires the --agents flag.

Notes

  • Rerun this command whenever you install or remove @arkyn/* packages, so the linked list in AGENTS.md stays accurate.
  • Nothing is left installed in your project after running it via npx/bunx.
Related in Commands
On this page
    arkyn