> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ntropii.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ntro CLI

> Command-line interface for Ntropii — connections, tenants, entities, workflows, and runs.

The `ntro` CLI is a thin layer over the Python SDK. Every command parses arguments, calls the SDK, and formats output. No business logic lives in the CLI itself.

## Install

<Tabs>
  <Tab title="pip (production)">
    ```bash theme={null}
    pip install ntro-cli
    ntro --help
    ```
  </Tab>

  <Tab title="Editable (local dev)">
    ```bash theme={null}
    uv venv ~/.ntro-dev --python 3.12
    source ~/.ntro-dev/bin/activate

    uv pip install -e ~/ntropii/ntro-python
    uv pip install -e ~/ntropii/ntro-cli

    ntro --help
    ```
  </Tab>
</Tabs>

## First-time setup

```bash theme={null}
ntro auth login
ntro auth whoami      # Confirm the key works
ntro tenant list      # Confirm you can see your tenants
```

`auth login` writes `~/.ntro/config.toml` — see [API keys](/get-started/api-keys) and [Configure environment](/get-started/configure-environment) for the full flow.

## Global flags

All flags go *before* the subcommand:

```bash theme={null}
ntro [OPTIONS] COMMAND [ARGS]...
```

| Flag                    | Description                                                         |
| ----------------------- | ------------------------------------------------------------------- |
| `-c, --connection NAME` | Connection from `config.toml` (env: `NTRO_DEFAULT_CONNECTION_NAME`) |
| `--host URL`            | Override the API host (env: `NTRO_HOST`)                            |
| `-o, --output FORMAT`   | `text` (default — Rich tables) or `json`                            |
| `--debug`               | Enable debug logging                                                |
| `--log-level LEVEL`     | `DEBUG`, `INFO`, `WARN`, `ERROR`                                    |

```bash theme={null}
ntro -c production -o json tenant list | jq '.[].slug'
```

## Command groups

<AccordionGroup>
  <Accordion title="ntro auth — connections and identity">
    ```bash theme={null}
    ntro auth login                           # Interactive setup
    ntro auth login --no-interactive \        # CI/CD setup
      --name production \
      --host https://api.ntropii.com/v1 \
      --api-key ntro_prod_xxx \
      --default-tenant acme-fund

    ntro auth list                            # All configured connections
    ntro auth test                            # Test the active connection
    ntro auth test -c staging                 # Test a specific connection
    ntro auth set-default production          # Change the default
    ntro auth whoami                          # Current user identity
    ```
  </Accordion>

  <Accordion title="ntro integration — data platforms (BYO only)">
    Used when bringing your own data platform (Snowflake or Microsoft Fabric). Skip this if you're using `managed-postgres` — Ntropii provisions and manages the database for you.

    ```bash theme={null}
    # Register a Snowflake account
    ntro integration add snowflake \
      --name "Acme Snowflake UK" \
      --account acme-fund.eu-west-2 \
      --warehouse fund_ops \
      --user ntropii \
      --password <secret> \
      --region UK-South

    # Or use --json for the full payload
    ntro integration add snowflake --json @./snowflake-config.json

    ntro integration list
    ntro integration info <id>
    ntro integration test <id>
    ntro integration discover <id>            # List schemas in the warehouse
    ```
  </Accordion>

  <Accordion title="ntro tenant — clients">
    Every tenant must declare its data-platform strategy at creation. Required values: `managed-postgres`, `snowflake`, or `microsoft-fabric`.

    ```bash theme={null}
    # Managed Postgres — Ntropii provisions the database
    ntro tenant create \
      --name "Acme Fund" \
      --slug acme-fund \
      --data-platform managed-postgres

    # BYO — register the config first, then bind it
    ntro integration add snowflake --name "..." ...
    # → dpc_abc123

    ntro tenant create \
      --name "Acme Fund" \
      --slug acme-fund \
      --data-platform snowflake \
      --data-platform-config dpc_abc123

    ntro tenant list
    ntro tenant info acme-fund
    ```

    The CLI fails fast when `--data-platform-config` is set with `managed-postgres`, or missing with a BYO platform. The API enforces the same checks server-side.
  </Accordion>

  <Accordion title="ntro entity — SPVs and funds">
    ```bash theme={null}
    ntro entity create \
      --name "Acme Commercial SPV 1" \
      --slug acme-commercial-spv1 \
      --tenant acme-fund \
      --type real-estate-spv \
      --jurisdiction Jersey \
      --currency GBP

    ntro entity list
    ntro entity list --tenant acme-fund
    ```

    Tenant resolution: `--tenant` flag → `NTRO_TENANT` env var → `default_tenant` in config.
  </Accordion>

  <Accordion title="ntro workflow — deploy runbooks, bind to entities, run">
    `ntro workflow create --path` is a single command that does runbook deploy + workflow binding. Per [N-80](https://linear.app/byng/issue/N-80), workflows are anchored to a `runbookSlug`; the same runbook can back many workflows across tenants and entities.

    ```bash theme={null}
    # Deploy a runbook + bind it to an entity + add a schedule
    ntro workflow create \
      --path ./runbooks/nav-monthly/ \
      --tenant acme-fund \
      --entity acme-spv1 \
      --schedule "0 8 5 * *" \
      --timezone Europe/London

    # Update runbook code only (no --entity = no workflow row)
    ntro workflow create \
      --path ./runbooks/nav-monthly/ \
      --tenant acme-fund

    # Pin the workflow to the version deployed by THIS command
    # (without --pin, the workflow follows whatever's currently on the worker)
    ntro workflow create \
      --path ./runbooks/nav-monthly/ \
      --tenant acme-fund \
      --entity acme-spv1 \
      --pin

    ntro workflow list                        # All entity → runbook bindings
    ntro workflow info <id>                   # Detail + current runbookVersion

    # Trigger a run
    ntro workflow run nav-monthly \
      --tenant acme-fund \
      --entity acme-spv1 \
      --period 2026-03

    ntro workflow run nav-monthly --tenant acme-fund --wait     # Poll until complete
    ntro workflow run nav-monthly --tenant acme-fund --dry-run
    ```

    `ntro workflow test` is covered in [Testing locally](/deploy-and-run/testing-locally).
  </Accordion>

  <Accordion title="ntro runbook — list and inspect runbook templates">
    Runbooks are the deterministic Python templates that drive workflows. The CLI surfaces the templates installed on the worker for browsing and feedback.

    ```bash theme={null}
    ntro runbook list                         # All registered runbooks on the worker
    ntro runbook info nav-monthly             # Detail + frontmatter + skill definition
    ntro runbook templates nav-monthly        # Get the full templates payload
    ntro runbook feedback nav-monthly \       # Submit feedback against a runbook
      --message "Period close took longer than expected" \
      --task <task-id>
    ```

    To deploy a runbook, use `ntro workflow create --path` (see above) — it wraps the runbook deploy + workflow binding in a single command.
  </Accordion>

  <Accordion title="ntro agent — register and inspect external agents">
    External agents are references to Managed Agents on host platforms (Anthropic, GitHub/Microsoft, …). Registering them with Ntropii makes them addressable by Ntropii UUID from inside a runbook step.

    ```bash theme={null}
    # Register an Anthropic-hosted Managed Agent
    ntro agent create \
      --path anthropic://agents/agent_01SxpziMunFrUbnAYkGB5Hu3 \
      --tenant byng \
      --name audit-handover
    # Returns the Ntropii agent UUID + API key plaintext (shown once).
    # Store the plaintext in an Anthropic Vault.

    ntro agent list --tenant byng             # All registered agents under a tenant
    ntro agent info <agent-id>                # Detail + kind + externalRef
    ntro agent delete <agent-id> --yes        # Tear down the registration
    ```

    See [Register agents](/workflows/agents/register) for the full lifecycle.
  </Accordion>

  <Accordion title="ntro run — inspect executions">
    ```bash theme={null}
    ntro run status <task-id>                 # Single run status + step progress
    ntro run list                             # Scheduled / active runs
    ntro run history \                        # History for an entity
      --tenant acme-fund \
      --entity acme-spv1
    ntro run incoming                         # Queued runs
    ntro run pending                          # Runs awaiting human action
    ```

    Note the linguistic split: `ntro workflow run <name>` is a verb (execute the workflow). `ntro run status <id>` is a noun (look at the run).
  </Accordion>
</AccordionGroup>

## The `--json` pattern

Write commands accept `--json` for complex payloads:

```bash theme={null}
# Inline
ntro tenant create --json '{"name":"Acme","slug":"acme","dataPlatformConfigId":"dpc_123"}'

# From file (@ prefix, Databricks CLI convention)
ntro integration add databricks --json @./databricks.json
```

## Output formats

```bash theme={null}
# Default: Rich tables and panels
ntro tenant list

# JSON for scripting
ntro -o json tenant list | jq '.[].slug'
ntro -o json auth whoami | jq .email
```

## Related

<CardGroup cols={2}>
  <Card title="MCP server" icon="plug" href="/tooling/mcp-server">
    Same surface, exposed to coding agents over MCP.
  </Card>

  <Card title="Testing locally" icon="flask" href="/deploy-and-run/testing-locally">
    `ntro workflow test` for the design-time inner loop.
  </Card>
</CardGroup>