Skip to main content
nanograph

Project Config

NanoGraph supports a project-level nanograph.toml plus local env files for secrets and machine-specific overrides.

Use this for:

  • default DB and schema paths
  • query roots
  • query aliases
  • embedding defaults
  • CLI output defaults

Use .env.nano for local secrets like OPENAI_API_KEY.

Files

nanograph.toml

Shared project defaults. Safe to commit.

Typical contents:

[project]
name = "Star Wars"
description = "Searchable Star Wars graph."
instruction = "Prefer aliases for common queries."

[db]
default_path = "starwars.nano"

[schema]
default_path = "starwars.pg"

[query]
roots = ["."]

[embedding]
provider = "mock"
model = "text-embedding-3-small"
batch_size = 64
chunk_size = 0
chunk_overlap_chars = 128
api_key_env = "OPENAI_API_KEY"

[cli]
output_format = "table"
json = false

[query_aliases.search]
query = "starwars.gq"
name = "semantic_search"
args = ["q"]
format = "table"

.env.nano

Local-only secrets and machine-specific overrides. Do not commit this file.

OPENAI_API_KEY=sk-...

You can also put non-secret local overrides here, but the intended use is secrets.

.env

NanoGraph also loads ./.env after ./.env.nano. It is a fallback compatibility path, not the preferred place for NanoGraph secrets.

Discovery

Config discovery is intentionally simple:

  • if you pass --config <path>, NanoGraph loads that file
  • otherwise, it looks for ./nanograph.toml
  • it does not walk parent directories

Env files are loaded from the config base directory:

  • when --config path/to/nanograph.toml is used, NanoGraph looks for path/to/.env.nano and path/to/.env
  • otherwise, it looks in the current working directory

Precedence

Command defaults

For command settings like DB path, query path, alias name, and output format:

  1. explicit CLI flags
  2. query_aliases.<alias>
  3. shared config defaults such as db.default_path, schema.default_path, and cli.output_format

Embedding env and secrets

For embedding-related env like OPENAI_API_KEY:

  1. existing process environment
  2. .env.nano
  3. .env
  4. [embedding] values in nanograph.toml
  5. engine defaults

This is why the recommended setup is:

  • keep OPENAI_API_KEY in .env.nano
  • keep shared embedding defaults like provider and model in nanograph.toml

Supported sections

[project]

Advisory project metadata.

[project]
name = "Acme Graph"
description = "Operational context graph for customer work."
instruction = "Prefer trace queries before ad hoc search."

Currently this is descriptive metadata for humans and agents. It does not change engine behavior.

[db]

Default database path for commands that operate on a DB.

[db]
default_path = "app.nano"

With this set, commands like these can omit --db:

nanograph describe
nanograph export
nanograph run search "vector databases"

[schema]

Default schema path, mainly used by init.

[schema]
default_path = "schema.pg"

[query]

Query file search roots for check and run.

[query]
roots = ["queries", "examples"]

If a relative query path is not found directly, NanoGraph searches these roots in order.

[embedding]

Shared embedding defaults.

[embedding]
provider = "openai"   # or "mock"
model = "text-embedding-3-small"
base_url = "https://api.openai.com/v1"
batch_size = 64
chunk_size = 0
chunk_overlap_chars = 128
api_key_env = "OPENAI_API_KEY"

Supported fields:

  • provider — openai or mock
  • model
  • base_url
  • mock
  • batch_size
  • chunk_size
  • chunk_overlap_chars
  • api_key_env

Do not put raw API keys in nanograph.toml.

[cli]

Shared CLI defaults.

[cli]
output_format = "table"
json = false

output_format is used when a command supports multiple formats and no explicit --format is passed.

[query_aliases.<alias>]

Shortcuts for nanograph run. They work for both read and mutation queries.

[query_aliases.search]
query = "queries/search.gq"
name = "semantic_search"
args = ["q"]
format = "table"

Then:

nanograph run search "father and son conflict"

Multi-parameter aliases work the same way:

[query_aliases.family]
query = "queries/search.gq"
name = "family_semantic"
args = ["slug", "q"]
format = "table"
nanograph run family luke-skywalker "chosen one prophecy"

Explicit --param values still work and override alias-derived positional params when both are present.

init scaffolding

When missing, nanograph init scaffolds:

  • nanograph.toml
  • .env.nano

It writes them into the inferred project directory shared by the DB path and schema path.

The generated config includes:

  • db.default_path
  • schema.default_path
  • query.roots = ["queries"]
  • default [embedding] keys
  • a commented alias example

What does not belong here

nanograph.toml is not live database state.

Do not use it for:

  • manifest values
  • tx / CDC cursors
  • dataset versions
  • any other engine-managed runtime state

That state already lives inside the database folder.

See also

CLITypeScript