Updating ARI

ARI is built to evolve. You can pull the latest updates from GitHub and get new features, bug fixes, and security patches — without losing any of your custom work.

How Updates Work

When you update ARI, core application files and everything inside modules-core/ are overwritten with the latest version. This keeps your installation current and secure. The modules-core directory is managed entirely by the upstream repository and should be treated as read-only — any local changes you make directly to modules in modules-core will be lost on the next update.

Your custom modules in modules-custom/ are completely untouched. That directory is yours — ARI will never modify or overwrite anything in it. Update with confidence.

Where to Put Your Modules

Always build new modules in modules-custom/. This is your space to extend ARI however you want, and it's fully protected from updates. Never edit files directly in modules-core/ — those changes won't survive the next update.

Customizing Core Modules

This is where ARI's architecture really shines. Want to tweak a built-in module? Just copy it from modules-core/ into modules-custom/ with the same name.

To customize an existing core module:

1. Duplicate the module folder from modules-core and place it in modules-custom with the same folder name.
2. Make your changes in the modules-custom copy.
3. Update freely — your custom version is safe.

ARI automatically loads modules-custom/ first. Your copy takes priority and the original is ignored — no configuration needed. Customize the look, change the logic, add fields, make it yours.

You can even customize the Dashboard the same way - the Dashboard is a module located modules-core/dashboard. Duplicate the folder and move it to the module-custom directory: modules-custom/dashboard.

Want to go back to the original? Delete your copy from modules-custom/ and the core version loads again instantly. Zero risk experimentation.

This means you can:

• Fork a core module and tweak it to fit your workflow.
• Fix a bug in a core module locally while waiting for an upstream patch.
• Experiment with changes to a module without affecting the original.

Backup Before Updating

Before pulling an update, make sure you have a recent backup of all ARI files including:

• Your modules-custom/ directory
• Your .env.local configuration file.
• Your database (use ARI's built-in backup feature under Settings, or export directly from your database interface).
• Any uploaded files stored in the data/ directory.

Updates are designed to be non-destructive, but regular backups are always important.

How to Update

Option 1: ARI CLI

The easiest way to update. Change into your ARI directory (cd ~/ARI or wherever you installed ARI) and run:

./ari update

This shows you what's changed, asks for confirmation, pulls the latest code, and installs any new dependencies. Run ./ari start afterward to launch.

Option 2: Update Using Claude

If you use Claude Code, type /ari-update in your terminal. Claude provides a fully interactive upgrade process:

1. Adds the upstream remote if missing
2. Fetches the latest changes
3. Shows you what's new before merging
4. Merges after your confirmation
5. Runs post-update tasks: dependency installs, new SQL migrations, module registry regeneration, and env var changes

It also checks for uncommitted changes and walks you through any conflicts. See Commands for more details.

Option 3: Manual Git Pull

You can also update ARI directly with Git:

git remote add upstream https://github.com/ARIsoftware/ARI.git
git pull upstream main

After updating using git pull, run pnpm install to pick up any new dependencies, then restart with ./ari start.

Manual Update Workflow

When updating manually, follow these steps:

1. Commit or back up your work before pulling upstream changes.
2. Pull the latest changes from the upstream repository.
3. Review any conflicts — these should only occur if you edited files outside of modules-custom.
4. Test your modules to make sure everything still works with the updated core.

Summary

Keep your customizations in modules-custom and you can update ARI with confidence.