Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/neo4j-labs/neocarta/llms.txt

Use this file to discover all available pages before exploring further.

The Neocarta CLI (pip install "neocarta[cli]") wraps all connector classes behind a consistent noun-verb command grammar so you can drive ingestion, run graph queries, and start the MCP server without writing Python. The CLI is designed to be agent-friendly first — stable JSON output, documented exit codes, non-interactive by default, and an agent-context introspection command for AI agents to discover capabilities at runtime.

​
Install

pip install "neocarta[cli]"
The [cli] extra adds click, rich, and pydantic-settings on top of the base library. The MCP server (neocarta mcp serve) additionally needs pip install "neocarta[mcp]", and Databricks support requires pip install "neocarta[databricks]".

​
Global Options

These flags are accepted by the top-level neocarta group and apply to every subcommand.
FlagDescription
--json / -jEmit JSON on stdout. Auto-enabled when stdout is not a TTY (pipe, CI).
--log-level [DEBUG|INFO|WARNING|ERROR]Diagnostics verbosity on stderr. Default: INFO.
--debugAlias for --log-level DEBUG. Emits verbose diagnostics on stderr.
--no-colorSuppress ANSI colors in output. NO_COLOR=1 env var also honored.
-v / --versionPrint the CLI version and exit.
-h / --helpShow help and exit.
Pass --debug when troubleshooting connector failures: it also prints the full chained exception traceback to stderr, including the original vendor exception that caused the error.

​
Command Tree

The CLI organizes commands as neocarta <noun> <verb>. Every connector command follows the same pattern: flag overrides > environment variables > built-in defaults.
CommandDescription
neocarta bigquery schemaExtract BigQuery schema metadata (Database, Schema, Table, Column) into Neo4j
neocarta bigquery logsExtract BigQuery query logs from INFORMATION_SCHEMA.JOBS_BY_PROJECT
neocarta csv ingestLoad metadata from a directory of CSV files
neocarta dataplex schemaLoad BigQuery schema from the Dataplex Universal Catalog
neocarta dataplex glossaryLoad a Dataplex business glossary (Glossary, Category, BusinessTerm)
neocarta jdbc schemaExtract schema from any JDBC-accessible database via SchemaCrawler
neocarta osi ingestLoad an OSI YAML semantic model from a local path or HTTP(S) URL
neocarta osi exportExport an OSI semantic model from Neo4j back to a YAML file
neocarta query-log ingestParse a query-log JSON file into Query and reference nodes
neocarta databricks tagsLoad Databricks Unity Catalog governed-tag definitions
neocarta tool <tool>Query the semantic graph directly, mirroring every MCP server tool
neocarta mcp serveStart the Neocarta MCP server over stdio
neocarta agent-contextEmit the full CLI shape as JSON for AI agents to consume

​
Exit Codes

The CLI uses a closed exit-code map. Renaming a code’s meaning is a breaking change.
Exit CodeNameDescription
0successSuccess, including empty results
1general_failureGeneral or unexpected failure
2usage_errorBad flag, missing required argument, or malformed input
3not_foundNamed resource or required index does not exist
4auth_errorMissing or invalid credentials
5conflictResource already exists or concurrent modification detected
6validation_errorInput was syntactically valid but semantically rejected
7rate_limitedRate limited or quota exceeded
8upstream_errorTransient upstream service failure
124timeoutOperation exceeded its timeout
In --json mode, errors are also emitted to stdout under an { "error": {...} } envelope so agents can parse them without reading stderr. Human-readable diagnostics always go to stderr.

​
JSON Output Format

All commands support --json output. The flag is automatically enabled when stdout is not a TTY (e.g. when piping to jq or running in CI). Success envelope — keyed by the command name: 
{
  "bigquery_schema": {
    "project_id": "my-proj",
    "dataset_id": "sales",
    "database": "neo4j",
    "embeddings": true,
    "status": "succeeded"
  }
}
Error envelope — always under the error key: 
{
  "error": {
    "code": "usage_error",
    "exit_code": 2,
    "message": "Missing required setting: --project-id.",
    "retryable": false,
    "suggestion": "Pass --project-id on the command line or set GCP_PROJECT_ID."
  }
}
Tool commands (neocarta tool *) use the tool_<tool_name> key, e.g. { "tool_list_schemas": { "count": 3, "results": [...] } }.

​
Neo4j Connection Flags

Every connector command accepts three per-invocation overrides for the Neo4j connection. These take priority over the corresponding environment variables.
FlagOverrides env varDefault
--neo4j-uriNEO4J_URI—
--neo4j-usernameNEO4J_USERNAME—
--neo4j-databaseNEO4J_DATABASEneo4j
NEO4J_PASSWORD is never a CLI flag. It is read exclusively from the environment variable to keep the secret out of shell history and the process list.

​
Output Discipline

stdout — results only

Carries the command result. In JSON mode, a single top-level JSON object. In TTY mode, a short human-readable summary. Never mixes diagnostics.

stderr — diagnostics only

Carries progress spinners, log output, and error messages. Never carries the result payload. Errors appear here in human-readable form regardless of --json mode.

​
Agent Integration Notes

1

Discover the command surface

Call neocarta agent-context once to obtain the full command tree, flags, exit codes, and recognized env vars as a single JSON document. Cache it for the duration of a session.
neocarta agent-context | jq '.commands.bigquery.subcommands.schema.flags'
2

Validate before committing

Every write-capable command supports --dry-run, which performs zero side effects and prints the planned action as JSON. Use it to validate inputs before committing.
neocarta bigquery schema --project-id my-proj --dataset-id sales --dry-run --json
3

Handle structured errors

The CLI is non-interactive and never prompts. On failure it exits with a documented exit code and emits a structured { "error": {...} } envelope to stdout (in JSON mode) alongside a human-readable message on stderr.

Build docs developers (and LLMs) love

Get started for freeTalk to us