Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

nao CLI

Command-line interface for nao chat.

Installation

Install the core package (lightweight, no database or LLM dependencies):

pip install nao-core

Then add only the providers you need:

# Database backends
pip install 'nao-core[postgres]'
pip install 'nao-core[bigquery]'
pip install 'nao-core[snowflake]'
pip install 'nao-core[duckdb]'
pip install 'nao-core[clickhouse]'
pip install 'nao-core[databricks]'
pip install 'nao-core[mysql]'
pip install 'nao-core[mssql]'
pip install 'nao-core[athena]'
pip install 'nao-core[trino]'
pip install 'nao-core[redshift]'
pip install 'nao-core[fabric]'
pip install 'nao-core[starrocks]'

# LLM providers
pip install 'nao-core[openai]'
pip install 'nao-core[anthropic]'
pip install 'nao-core[mistral]'
pip install 'nao-core[gemini]'
pip install 'nao-core[ollama]'

# Integrations
pip install 'nao-core[notion]'

# Semantic layer (dbt MetricFlow)
pip install 'nao-core[semantic-layer]'

Obsidian support is included in the core package and does not require an extra.

Combine multiple extras in a single install:

pip install 'nao-core[postgres,openai]'
pip install 'nao-core[snowflake,bigquery,anthropic]'

Or install everything at once (equivalent to the previous default):

pip install 'nao-core[all]'

Convenience groups are also available:

pip install 'nao-core[all-databases]'  # all database backends
pip install 'nao-core[all-llms]'       # all LLM providers

Usage

nao --help
Usage: nao COMMAND

╭─ Commands ────────────────────────────────────────────────────────────────╮
│ chat         Start the nao chat UI.                                       │
│ debug        Test connectivity to configured resources.                   │
│ init         Initialize a new nao project.                                │
│ sync         Sync resources to local files.                               │
│ test         Run and explore nao tests.                                   │
│ --help (-h)  Display this message and exit.                               │
│ --version    Display application version.                                 │
╰───────────────────────────────────────────────────────────────────────────╯

Initialize a new nao project

nao init

This will create a new nao project in the current directory. It will prompt you for a project name and ask you to configure:

  • Database connections (BigQuery, DuckDB, MotherDuck, DuckLake, Databricks, Snowflake, PostgreSQL, Redshift, MSSQL, Trino, StarRocks)
  • Git repositories to sync
  • LLM provider (OpenAI, Anthropic, Mistral, Gemini, OpenRouter, Requesty, Ollama)
  • ai_summary template + model (prompted only when you enable ai_summary for databases)
  • Slack integration
  • Notion integration

The resulting project structure looks like:

<project>/
├── nao_config.yaml
├── .naoignore
├── RULES.md
├── databases/
├── queries/
├── docs/
├── semantics/
├── repos/
├── agent/
│   ├── tools/
│   └── mcps/
└── tests/

Options:

  • --force / -f: Force re-initialization even if the project already exists
  • --yes / -y / --no-tty: Run non-interactively. Skips all prompts and uses sensible defaults — useful for AI agents and automation scripts. When combined with a pre-written nao_config.yaml (e.g. written by an agent skill), only scaffolds the folder structure.
  • --name / -n: Project name. When set without an existing nao_config.yaml, this is used as the project name (and folder). In --yes mode without --name, the current directory name is used and the project is initialized in place.

Non-interactive (agent-friendly) mode

For LLM agents and automation, run nao init without any prompts:

# Initialize the current directory as a nao project (uses the directory name)
nao init --yes

# Or create a new sub-folder named "my-project"
nao init --yes --name my-project

# Pre-write nao_config.yaml then scaffold folders without prompting
cat > nao_config.yaml <<'YAML'
project_name: my-project
databases:
  - type: duckdb
    name: local
    path: ":memory:"
YAML
nao init --yes

# MotherDuck (DuckDB-compatible cloud) — token via env recommended
cat > nao_config.yaml <<'YAML'
project_name: my-project
databases:
  - type: motherduck
    name: md-analytics
    database: my_db
    token: "{{ env('MOTHERDUCK_TOKEN') }}"
YAML
nao init --yes

# DuckLake — a postgres or mysql catalog is recommended for concurrent access;
# file-based catalogs (duckdb/sqlite) allow only a single connection at a time.
# The session denies local filesystem and network access once the lake is
# attached, so queries can only read the configured lake, not arbitrary files.
cat > nao_config.yaml <<'YAML'
project_name: my-project
databases:
  - type: ducklake
    name: lake
    catalog:
      type: postgres
      host: localhost
      port: 5432
      database: ducklake_catalog
      user: "{{ env('DUCKLAKE_CATALOG_USER') }}"
      password: "{{ env('DUCKLAKE_CATALOG_PASSWORD') }}"
    data_path: "s3://my-bucket/lake/"
    storage:
      type: s3
      key_id: "{{ env('AWS_ACCESS_KEY_ID') }}"
      secret: "{{ env('AWS_SECRET_ACCESS_KEY') }}"
      region: eu-west-1
YAML
nao init --yes

In non-interactive mode, nao init never asks for input. Configure databases, LLM provider, and integrations by editing nao_config.yaml directly (or by pre-writing it before nao init).

Start the nao chat UI

nao chat

This will start the nao chat UI. It will open the chat interface in your browser at http://localhost:5005.

To let the agent run code in a micro-VM, download the sandbox runtime once with nao chat --sandbox, then enable Sandboxes in Settings → Experimental. The runtime and the DuckDB engine used by nao test are ~100 MB each, so they are not shipped in the package: nao fetches them on first use and caches them in ~/.nao/native. Set NAO_NATIVE_REGISTRY to download them from an npm mirror instead of registry.npmjs.org.

Test connectivity

nao debug

Tests connectivity to all configured databases and LLM providers. Displays a summary table showing connection status and details for each resource.

Sync resources

nao sync

Syncs configured resources to local files:

  • Databases - generates configured markdown docs for each table into databases/ (columns.md and preview.md by default; optional profiling.md, query_history.md, and ai_summary.md)
  • Git repositories — clones or pulls repos into repos/
  • Notion pages — exports pages as markdown into docs/notion/. Databases are exported as markdown tables, whether configured directly or embedded inline in a page. A database embedded in a page is exported through one of its views — Notion exposes no way to tell which view a page renders, so the first one listed is used — applying that view's filters, sorts and visible columns rather than dumping the whole data source. A database configured by URL exports every row and column, unless the URL carries ?v=<view_id>, in which case that view applies. When a database cannot be exported, its page fails to sync and the previously synced markdown is left untouched, rather than being rewritten without its table.
  • Obsidian notes — copies markdown notes from a local vault into docs/obsidian/, skipping hidden folders such as .obsidian/ and .trash/

After syncing, any Jinja templates (*.j2 files) in the project directory are rendered with the nao context.

Optional ai_summary generation:

  • Add ai_summary to a database connection templates list to render ai_summary.md.
  • AI summaries use profiling statistics for data-quality and distribution observations. The row preview is a tiny, non-representative shape sample.
  • Use prompt("...") inside Jinja templates to generate ai_summary content.
  • prompt(...) requires an llm.providers entry with an api_key (except for ollama), plus llm.annotation_model.
  • Configure profiling and ai_summary refreshes independently with refresh_policy: always, once, or interval. Interval policies also accept interval_days (default: 7):
databases:
    - type: duckdb
      name: analytics
      path: analytics.duckdb
      templates: [columns, preview, profiling, ai_summary]
      profiling:
          refresh_policy: once
      ai_summary:
          refresh_policy: interval
          interval_days: 7

Log in

nao login

Connects the CLI to your nao account: it opens the app in your browser, asks you to approve the CLI, and stores the resulting session. Commands that talk to the backend (like nao test) trigger the same browser flow automatically when you are not logged in yet, and fall back to an email/password prompt when no browser is available. Use nao logout to revoke the stored session.

Run tests

nao test

Runs test cases defined as YAML files in tests/. Each test has a name, prompt, and optional expected sql and/or assertions. Results are saved to tests/outputs/.

Final-output checks use reference sql (dataframe equality). Intermediate agent actions use assertions against the run's tool-call trace — for example, requiring a clarifying follow-up:

name: ambiguous_revenue_period
prompt: What was the revenue?
assertions:
  - type: tool_call
    tool: clarification

tool_call assertions can also require a specific tool (e.g. execute_sql), optional arg subset match via args (omit it to match any call; an empty mapping is rejected), and min_count. SQL verification and assertions can be combined; the run passes only if every check passes. A test file with an invalid assertions block fails the whole run instead of being skipped.

Options:

  • --model / -m: Models to test against (default: openai:gpt-4.1). Can be specified multiple times.
  • --threads / -t: Number of parallel threads (default: 1)
  • --k / -k: Number of times to run each test case, used to compute pass@k and pass^k (default: 1)
  • --select / -s: Run only selected tests by name, yaml stem, or subfolder. Comma-separated.
  • --username / -u, --password: Credentials for the nao backend, for non-interactive runs. Fall back to NAO_USERNAME / NAO_PASSWORD. When omitted, the CLI uses your stored login or opens the browser login flow.

Examples:

nao test -m openai:gpt-4.1
nao test -m openai:gpt-4.1 -m anthropic:claude-sonnet-4-20250514
nao test --threads 4
nao test --k 5

Defaults for every run live in the test block of nao_config.yaml, and the --model / --threads / --k flags override them:

test:
    models:
        - openai:gpt-4.1
        - anthropic:claude-sonnet-4-5
    threads: 4
    # k: 5  # run each case 5 times to compute pass@k / pass^k
    comparison:
        rtol: 0.00001
        atol: 0.00000001
        decimals: 2

Explore test results

nao test server

Starts a local web server to explore test results in a browser UI showing pass/fail status, token usage, cost, and detailed data comparisons.

Options:

  • --port / -p: Port to run the server on (default: 8765)
  • --no-open: Don't automatically open the browser

BigQuery service account permissions

When you connect BigQuery during nao init, the service account used by credentials_path/ADC must be able to list datasets and run read-only queries to generate docs. Grant the account:

  • Project: roles/bigquery.jobUser (or roles/bigquery.user) so the CLI can submit queries
  • Each dataset you sync: roles/bigquery.dataViewer (or higher) to read tables

The combination above mirrors the typical "BigQuery User" setup and is sufficient for nao's metadata and preview pulls.

Snowflake authentication

Snowflake supports three authentication methods during nao init:

  • SSO: Browser-based authentication (recommended for organizations with SSO policies)
  • Password: Traditional username/password
  • Key-pair: Private key file with optional passphrase

Development

Building the package

cd cli
python build.py --help
Usage: build.py [OPTIONS]

Build and package nao-core CLI.

╭─ Parameters ──────────────────────────────────────────────────────────────────╮
│ --force -f --no-force              Force rebuild the server binary             │
│ --skip-server -s --no-skip-server  Skip server build, only build Python pkg   │
│ --bump                             Bump version (patch, minor, major)          │
╰───────────────────────────────────────────────────────────────────────────────╯

This will:

  1. Build the frontend with Vite
  2. Compile the backend with Bun into a standalone binary
  3. Bundle everything into a Python wheel in dist/

Installing for development

cd cli
pip install -e '.[all]'

Publishing to PyPI

# Build first
python build.py

# Publish
uv publish dist/*

Architecture

nao chat (CLI command)
    ↓ spawns
nao-chat-server (Bun-compiled binary, port 5005)
  + FastAPI server (port 8005)
    ↓ serves
Backend API + Frontend Static Files
    ↓
Browser at http://localhost:5005

Metadata

Release files for nao-core 0.4.3rc1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for nao-core 0.4.3rc1
File Actions
nao_core-0.4.3rc1-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for nao_core-0.4.3rc1-py3-none-win_amd64.whl
nao_core-0.4.3rc1-py3-none-manylinux2014_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for nao_core-0.4.3rc1-py3-none-manylinux2014_x86_64.whl
nao_core-0.4.3rc1-py3-none-manylinux2014_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for nao_core-0.4.3rc1-py3-none-manylinux2014_aarch64.whl
nao_core-0.4.3rc1-py3-none-macosx_15_0_x86_64.whl Python 3 none macOS 15.0+ x86-64 Details for nao_core-0.4.3rc1-py3-none-macosx_15_0_x86_64.whl
nao_core-0.4.3rc1-py3-none-macosx_15_0_arm64.whl Python 3 none macOS 15.0+ ARM64 Details for nao_core-0.4.3rc1-py3-none-macosx_15_0_arm64.whl

Total release size: 333.5 MB

Release files / nao_core-0.4.3rc1-py3-none-win_amd64.whl

Download URL nao_core-0.4.3rc1-py3-none-win_amd64.whl
Size 74.3 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
fd9fa2ab90c4a2feab7906de267612eea37df0eefa421b12ced26f9b43f3b214
BLAKE2b-256 checksum
How to use checksums
980d9741b9d0bdb1c6b179cfd335e5b6195b8e9d059f46a5d2d6335bfa7d9545
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / nao_core-0.4.3rc1-py3-none-manylinux2014_x86_64.whl

Download URL nao_core-0.4.3rc1-py3-none-manylinux2014_x86_64.whl
Size 73.4 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
4850f9d2df921f872784689e842942b47fbac718622c9403d95afa30865f6ad0
BLAKE2b-256 checksum
How to use checksums
5dde33360c7dad2facf08349b207ea8c51d7f8ad068b4612ecc732f99d5f4c5f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / nao_core-0.4.3rc1-py3-none-manylinux2014_aarch64.whl

Download URL nao_core-0.4.3rc1-py3-none-manylinux2014_aarch64.whl
Size 72.7 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
873c869b46554ba1f997a0b6ffe45d23b51b1745b2b8bedd6462882ebc27be48
BLAKE2b-256 checksum
How to use checksums
0cf3699c0bc444ea73a19f07fd5dae4a21443d99ea9ae1fcab03ba9b32a95e77
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / nao_core-0.4.3rc1-py3-none-macosx_15_0_x86_64.whl

Download URL nao_core-0.4.3rc1-py3-none-macosx_15_0_x86_64.whl
Size 58.0 MB
Tags Python 3 macOS 15.0+ x86-64
SHA-256 checksum
How to use checksums
eb1564c7a3cd9e8f5bc232c28aa205dbe1160d9f1434955eec8bddce91b9f791
BLAKE2b-256 checksum
How to use checksums
fae4faa8031566a6c6f15c1b55af6619d98b70353f4cd1a90ec5d56eb2a6be87
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / nao_core-0.4.3rc1-py3-none-macosx_15_0_arm64.whl

Download URL nao_core-0.4.3rc1-py3-none-macosx_15_0_arm64.whl
Size 55.1 MB
Tags Python 3 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
59b47a8674dc592d1ab6f5b4d9b12705c09d8ebde2322b65b4cb4c5573675a6d
BLAKE2b-256 checksum
How to use checksums
c34f05dfec39971c2d6b478cfb018462458e26f961deb9c0bdcab012332cf610
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for nao-core 0.4.3rc1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for nao_core-0.4.3rc1-py3-none-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page