- Overview
- Examples
- How It Works
- Troubleshooting
Usage
Copy
Ask AI
elizaos update [options]
Options
| Option | Description |
|---|---|
-c, --check | Check for available updates without applying them |
--skip-build | Skip building after updating |
--cli | Update only the global CLI installation (without updating packages) |
--packages | Update only packages (without updating the CLI) |
Basic Update
Copy
Ask AI
# Update both CLI and project dependencies (default behavior)
elizaos update
Checking for Updates
Copy
Ask AI
# Check for available updates without applying them
elizaos update --check
Copy
Ask AI
$ elizaos update --check
Checking for updates...
Current CLI version: 1.3.5
Latest CLI version: 1.4.0
elizaOS packages that can be updated:
- @elizaos/core (1.3.0) → 1.4.0
- @elizaos/plugin-openai (1.2.5) → 1.4.0
To apply updates, run: elizaos update
Scoped Updates
Copy
Ask AI
# Update only the global CLI
elizaos update --cli
# Update only project packages
elizaos update --packages
Combined Options
Copy
Ask AI
# Check only for CLI updates
elizaos update --check --cli
# Update packages without rebuilding afterward
elizaos update --packages --skip-build
Update Process Explained
When you runelizaos update, it performs the following steps:- Detects Project Type: Determines if you’re in an elizaOS project or plugin.
- Checks CLI Version: Compares your installed CLI version with the latest available on npm.
- Scans Dependencies: Finds all
@elizaos/*packages in your project’spackage.json. - Shows Update Plan: Lists the packages and/or CLI that have available updates.
- Prompts for Confirmation: Asks for your approval before making any changes.
- Updates Packages: Installs the latest versions of the packages.
- Rebuilds Project: Compiles the updated dependencies (unless
--skip-buildis used).
Workspace & Monorepo Support
The update command is smart enough to detect monorepo workspaces. It will automatically skip any packages that are linked viaworkspace:* in your package.json, as these should be managed within the monorepo, not from the npm registry.Best Practices
Safe Update Process
For the smoothest update experience, follow this sequence:- Check what will be updated:
elizaos update --check - Commit your current work:
git commit -am "chore: pre-update savepoint" - Update the CLI first:
elizaos update --cli - Then, update project packages:
elizaos update --packages - Test your project thoroughly:
elizaos test
Project Detection
The update command automatically detects:- elizaOS Projects: Updates project dependencies and rebuilds
- elizaOS Plugins: Updates plugin dependencies and rebuilds
- Non-elizaOS Projects: Shows error message
Workspace Support
Monorepo Detection
- Automatically detects workspace references
- Skips packages with
workspace:*versions - Shows which packages are workspace-managed
Example with Workspaces
Copy
Ask AI
$ elizaos update --check
elizaOS packages found:
- @elizaos/core (workspace:*) → Skipped (workspace reference)
- @elizaos/plugin-openai (1.2.5) → 1.4.0
- @elizaos/plugin-discord (workspace:*) → Skipped (workspace reference)
Only non-workspace packages will be updated.
Version Strategy
Staying Current
- Update regularly to get latest features and fixes
- Use
--checkto monitor available updates - Subscribe to elizaOS release notes
Stability Considerations
- Test updates in development before production
- Consider pinning versions for production deployments
- Review changelogs for breaking changes
Troubleshooting
CLI Update Issues
If you have trouble updating the global CLI:Copy
Ask AI
# Check if the CLI is installed globally
bun pm ls -g @elizaos/cli
# If not, install it
bun install -g @elizaos/cli
# On macOS/Linux, you may need sudo
sudo bun install -g @elizaos/cli
# Or fix permissions on your bun directory
sudo chown -R $(whoami) ~/.bun
Package Update Failures
If package updates fail, a clean reinstall usually fixes it:Copy
Ask AI
# Clear caches and old dependencies
rm -rf node_modules
bun pm cache rm
rm bun.lockb
# Reinstall everything
bun install
Build Failures After Update
If your project fails to build after an update:Copy
Ask AI
# Try a clean build
bun run build
# Or try updating without the build step, then build manually
elizaos update --skip-build
bun install && bun run build
Version Mismatch Issues
Copy
Ask AI
# Check current versions
elizaos --version # CLI version
cat package.json | grep "@elizaos" # Package versions
# Force specific versions if needed
bun add @elizaos/[email protected] @elizaos/[email protected]
Network Issues
Copy
Ask AI
# If updates fail due to network
# Check npm registry
bun config get registry
# Reset to default if needed
bun config set registry https://registry.npmjs.org/
# Retry update
elizaos update
Monorepo Update Issues
Copy
Ask AI
# In monorepo, update workspace packages manually
cd packages/core
bun update
# Or update all workspaces
bun update --filter '*'