Upgrading ArcKit

Guide Origin: Official | ArcKit Version: [VERSION]

How to upgrade the ArcKit CLI and update your existing projects.

Step 1: Upgrade the CLI

# If installed with pip:
pip install --upgrade git+https://github.com/tractorjuice/arc-kit.git

# If installed with uv:
uv tool install --force arckit-cli --from git+https://github.com/tractorjuice/arc-kit.git

# Verify the new version:
arckit --help

Step 2: Update Your Existing Project

Navigate to your existing ArcKit project directory and re-run init with --here:

cd /path/to/your-existing-project

# Re-initialize in place (updates commands, templates, scripts)
arckit init --here --ai codex

What Gets Updated

Updated	Preserved
Skills (`.agents/skills/`)	Project data (`projects/`)
Default templates (`.arckit/templates/`)	Custom templates (`.arckit/templates-custom/`)
Helper scripts (`.arckit/scripts/`)
Documentation and guides (`docs/`)
`VERSION`, `CHANGELOG.md`

Note: For Claude Code users, commands and agents are provided by the ArcKit plugin and update automatically via the marketplace. No arckit init needed.

Note: For Gemini CLI users, use the ArcKit extension (gemini extensions install https://github.com/tractorjuice/arckit-gemini). Updates via gemini extensions update arckit.

Note: README.md will be overwritten. If you've customized it, back it up first:
cp README.md README.md.bak
arckit init --here --ai codex
mv README.md.bak README.md

Options

Flag	Description
`--ai codex`	Update Codex CLI commands
`--minimal`	Skip updating docs and guides

Step 3 (Optional): Migrate Legacy Filenames

If upgrading from v0.x to v1.x, your project artifacts may use old-style filenames (e.g., requirements.md, stakeholder-drivers.md). ArcKit v1.x uses standardized Document IDs:

Old: requirements.md
New: ARC-001-REQ-v1.0.md

Run the migration script to rename files automatically:

# Preview changes first (no files modified)
.arckit/scripts/bash/migrate-filenames.sh --all --dry-run

# Apply the migration
.arckit/scripts/bash/migrate-filenames.sh --all

The script:

Creates timestamped backups before making changes
Skips files that are already migrated
Handles subdirectories (decisions, diagrams, wardley-maps, etc.)
Moves legacy locations (e.g., .arckit/memory/principles.md to projects/000-global/)

See the migration guide for the complete filename mapping table and advanced options.

Checking Your Version

# Check installed CLI version
arckit --help

# Check project version (in an ArcKit project directory)
cat VERSION

Troubleshooting

"Directory already exists" error

Use --here (or .) to update an existing project in place:

# These are equivalent:
arckit init --here --ai codex
arckit init . --ai codex

Commands not updating

Make sure you upgraded the CLI first (Step 1), then re-ran init (Step 2). The init command copies the latest commands from the installed package.

Claude Code plugin or hook issue

Start Claude Code in safe mode before changing ArcKit files:

claude --safe-mode

You can also set CLAUDE_CODE_SAFE_MODE=1 for the session. Safe mode is the fastest way to isolate whether an ArcKit hook, command, skill, or installed plugin is involved.

disableBundledSkills disables Claude Code's bundled skills; it does not disable ArcKit plugin skills. To remove ArcKit from the test path, use safe mode, disable the plugin in /plugin, or uninstall the plugin.

Custom templates lost

Custom templates in .arckit/templates-custom/ are preserved across upgrades. Only default templates in .arckit/templates/ are refreshed. If you edited files in .arckit/templates/ directly (instead of .arckit/templates-custom/), those edits will be overwritten. Use /arckit:customize to set up the override workflow:

/arckit:customize requirements   # Copy template for safe customization