rayfin init ai-files
Install, refresh, disable, and audit Rayfin-managed agent files with rayfin init ai-files install and status.
rayfin init ai-files manages the agent context that Rayfin projects ship for coding
agents. Scaffolding runs it automatically; run it again after upgrading the CLI or when
rayfin up reports drift.
Managed items in 1.36.2
| Item | ID | Behavior |
|---|---|---|
AGENTS.md | one-time install | Seeded only when missing. Never overwritten by install, even with --force. |
.mcp.json mcpServers.rayfin key | mcp:rayfin | Owned by Rayfin. The CLI updates only the mcpServers.rayfin key and preserves other servers. |
.agents/skills/rayfin/SKILL.md | skill:rayfin | Core Rayfin project skill. |
.agents/skills/rayfin-functions/SKILL.md | skill:rayfin-functions | Functions skill. |
.agents/skills/rayfin-connectors/SKILL.md | skill:rayfin-connectors | Connectors skill. |
.agents/skills/rayfin-storage/SKILL.md | skill:rayfin-storage | Storage skill, installed only when the storage feature flag or service is enabled. New in 1.36 Experimental |
The lockfile is rayfin/.lockfile.json. Commit it so every developer sees the same
managed-item baseline.
ai-files install
npx rayfin init ai-files installIdempotently reconciles managed items with the bundled 1.36.2 assets.
| Option | Default | Description |
|---|---|---|
-f, --force [ids...] | no force | Overwrite managed items that were user-modified or restore missing items. With no IDs, applies to every managed item except AGENTS.md; with IDs, scopes the force. |
-y, --yes | false | Skip the interactive prompt. Alias of --non-interactive, redeclared so it works after the subcommand. |
--non-interactive | false | Skip the prompt and accept defaults: all items enabled. |
--enable <id> | [] | Enable a managed item. Repeatable. Skips the prompt. |
--disable <id> | [] | Disable a managed item and record the choice without writing the file. Repeatable. |
--remove-files | false | With --disable, also remove on-disk content for previously installed items. |
--json | false | Emit a single JSON envelope and suppress prompts. |
-n, --dry-run | false | Classify what would change without touching disk. |
ai-files status
npx rayfin init ai-files status --json| Option | Description |
|---|---|
--json | Emit a JSON object instead of formatted lines. |
Item states
| State | Meaning |
|---|---|
up-to-date | On disk and matches the bundled content recorded in the lockfile. |
update-available | On disk and untouched, but the current CLI ships newer content. |
user-modified | The user changed a managed file after the CLI wrote it. |
missing | The lockfile records an item that is no longer on disk. |
not-installed | The CLI knows about the item but has not installed it. |
disabled | Opted out by --disable, or for skills by removing the Rayfin-managed sigil. |
orphaned | The lockfile records an item the current CLI no longer ships. |
unreadable | The file exists but cannot be parsed, such as invalid JSON in .mcp.json. |
Exit codes
| Code | Meaning |
|---|---|
0 | Success without warnings. |
1 | Hard error. |
3 | Success with warnings, usually because user-modified content was preserved. |
Conflict resolution
The installer compares three things: the bundled asset in the current CLI, the lockfile entry that records what Rayfin last wrote, and the file currently on disk.
| State | Default install behavior | With --force |
|---|---|---|
not-installed | Install the item. | Install the item. |
up-to-date | No-op. | No-op. |
update-available | Rewrite with the new bundled content. | Rewrite with the new bundled content. |
user-modified | Warn and preserve the file. | Overwrite when the item is in force scope. |
missing | Warn and leave missing. | Reinstall when the item is in force scope. |
disabled | Skip. | Skip unless the item is also passed to --enable. |
unreadable | Warn and preserve. | Rebuild when the item is in force scope. |
orphaned, untouched | Remove lockfile and disk content. | Remove lockfile and disk content. |
orphaned, edited | Warn and preserve. | Remove when the item is in force scope. |
AGENTS.md is the exception. It is installed only when missing and is never overwritten by
install, even with --force.
Scripting examples
Check what would change without writing:
npx rayfin init ai-files install --dry-run --jsonRefresh in CI or an agent session while preserving user edits:
npx rayfin init ai-files install --yes --jsonForce only the MCP server entry after a malformed .mcp.json repair decision:
npx rayfin init ai-files install --force mcp:rayfin --yesDrift nudge
rayfin up prints this nudge when managed files are stale, modified, missing, or newly
available:
ℹ️ Your project's Rayfin agent files have changes available. Run `rayfin init ai-files install` to refresh.Run `npx rayfin init ai-files status --json`, then run
`npx rayfin init ai-files install --yes --json`. Preserve any user-modified items unless I
explicitly approve a scoped `--force <id>` overwrite.