Skip to main content
The @omni-co/model-local-editor CLI tool lets you edit Omni model YAML files in your local environment with real-time synchronization back to Omni. Changes you save locally are automatically pushed to your Omni branch and validated against the model, giving you full IDE support for syntax highlighting, autocomplete, and version control.
The Omni model editor CLI is currently in beta and under active development.

How it works

When you start the sync, your model’s YAML files are fetched from Omni and written to your local directory. From there, the CLI watches for file changes — any time you save, the updated file is pushed to your Omni branch and validated. When you’re ready, merging the branch promotes your changes to the shared model and syncs to git.

Prerequisites

Before starting local development:
  • Node.js version 16.0.0 or higher
  • Git integration is not required, but if you’re using it, the following settings are recommended:
    • Pull request required – Require all changes to be made through a pull request, preventing direct promotion of branch changes to the shared model.
    • Always create branches – When enabled, pull requests created outside Omni will automatically create a corresponding Omni branch.

Set up the CLI

Start by creating a new empty directory and opening it in your IDE. This is where the CLI will sync your model YAML files to — you don’t need to add any files yourself.

1. Install the package

Install the @omni-co/model-local-editor package globally: 
npm install -g @omni-co/model-local-editor

2. Set up environment variables

The CLI requires an API key and your Omni instance URL. Set them as environment variables: 
export OMNI_API_KEY="your-api-key"
export OMNI_BASE_URL="https://your-org.omniapp.co"
For persistence, add these to your ~/.bashrc, ~/.zshrc, or equivalent. You’ll also need your model ID. Navigate to your model in Omni and copy the UUID from the URL.

3. Create a branch and initialize the sync

If you don’t already have a branch, you can create one and initialize in a single step: 
omni-sync init your_model_id --branch your-branch --create-branch
If you already have a branch you want to use, pass it directly: 
omni-sync init your_model_id --branch your-branch

4. Start syncing

omni-sync start your_model_id
Once started, any changes you save are pushed to your Omni branch and run through the model validator. Errors and warnings surface in the terminal in real time.

5. Merge your changes

When you’re ready to promote your changes to the shared model, use the merge-branch command. This merges the branch into the shared model and syncs the changes to git. 
omni-sync merge-branch your_model_id your-branch
By default, the CLI will prompt you to confirm whether to delete the branch after merging. You can skip the prompt with one of the following flags:
  • --delete-branch – Delete the branch after a successful merge
  • --no-delete-branch – Keep the branch after merging
You can also pass a custom commit message for the git sync: 
omni-sync merge-branch your_model_id your-branch --delete-branch --commit-message "Your commit message"
If your model has Pull request required enabled in git settings, the CLI will not sync the merge to git. You can use --force-override-git-settings to allow the merge, but note that git will not be synced when this flag is used. To keep git in sync, merge via a pull request in your git provider instead.

AI tools for local development

You can extend your local development workflow with Omni’s AI integrations:
  • IDE plugins – Omni’s Cursor and Claude Code plugins bring analytics capabilities directly into your editor. Use them to explore models, run queries, and manage content without switching contexts.
  • MCP Server – Query your Omni data using natural language from AI tools like Cursor and Claude. Useful for validating changes by querying the model as you develop.

Troubleshooting

Missing schemas or tables

If schemas or tables you can see in the Omni IDE aren’t appearing in your local files, they may need to be activated. Make a small change to any file in that schema (such as updating a field description) and save it. This activates the schema and it will be included in subsequent syncs.

Additional resources

  • Git integration – Connect a git repository for version control and pull request workflows
  • Branch Mode – Use branches to develop and test model changes before sharing them
  • AI optimization – Curate your models for better results with Omni’s AI features