Skip to content

Get Started

Supported Platforms

  • Linux (x86_64 / ARM)
  • macOS (x86_64 / ARM)
  • Windows (x86_64)

Install

bash pip install nagi-cli

To use the MCP server, install with the mcp extra:

bash pip install nagi-cli[mcp]

Tip

If you want to try it out right away without setup, see Quickstart.

Project Structure

This page assumes you are setting up Nagi in a my-project/ directory.

Once setup is complete, the directory structure will look like this:

text my-project/ ├── nagi.yaml # Nagi configuration file ├── resources/ # Directory for resource definitions │ └── ... └── target/ # Directory referenced by Nagi for Sync and Evaluate ├── assets/ # Directory for compiled resource definitions │ └── ... └── graph.json # Asset dependency graph

Setup

1. Init

bash nagi init

Generates nagi.yaml and the resources/ directory through an interactive process.

When integrating with other software, also configure Origin and Connection.

With these configured, Nagi can read the settings of the integration target software and automatically generate Nagi definition files. See Integrations for supported software.

Origin also allows bulk configuration of automatic convergence. Configure according to your purpose:

Purpose Setting
Start with desired state evaluation Set autoSync: false
Perform state evaluation and convergence operations Set autoSync: true

After init completes, verify the following directory structure:

text my-project/ ├── nagi.yaml └── resources/ ├── connection.yaml # Only when Origin is configured └── origin.yaml # Only when Origin is configured

2. Define Resources

Place YAML files for resource definitions in resources/.

If Origin is already configured, Assets are automatically generated by nagi compile, so place Conditions here.

If not using Origin, place Asset, Conditions, and Connection.

See Resource Configurations for how to define each resource.

3. Compile

bash nagi compile

Validates and combines resource definitions in resources/, and outputs them to target/ as configuration for Evaluate and Sync.

text my-project/ ├── nagi.yaml ├── resources/ │ └── ... └── target/ # Generated by nagi compile ├── assets/ │ └── *.yaml # Compiled Assets └── graph.json # Dependency graph

4. Evaluate

bash nagi evaluate

Runs desired state evaluation against Assets in target/. If all conditions pass, the Asset evaluates to Ready; if any condition fails, it evaluates to Drifted.

To evaluate only a specific Asset, use --select:

bash nagi evaluate --select <asset-name>

What's Next