inconvo-cli

Inconvo CLI — Semantic Model Skill

Use this skill when you need to update an agent semantic model or user-context from code context. This repository uses a CLI-only mutation workflow.

Core Rules

1. Never edit .inconvo/** by hand.
2. Never use local YAML as mutation input.
3. Perform every remote change via inconvo model <group> <command>.
4. Let the CLI auto-refresh local .inconvo/ snapshots after successful mutations.
5. Use --dry-run to verify target resolution; it does not validate payload format.
6. Use --json for automation/agent workflows.
7. For many independent mutations, use --no-sync on each command and run inconvo model pull once at the end.
8. Use inconvo model pull after DB schema changes or to recover local snapshots.

Authentication

The CLI resolves credentials in this priority order (highest first):

1. --api-key / --api-base-url flags on the command
2. INCONVO_API_KEY / INCONVO_API_BASE_URL environment variables
3. Repo .env (INCONVO_API_KEY / INCONVO_API_BASE_URL)

Required Inputs

• agentId for all mutations (--agent). Read from .inconvo/agents/<slug>/agent.yaml.
• connectionId for schema mutations (--connection). Read from .inconvo/connections/<slug>/connection.yaml.
• Connection snapshots expose the platform connection context as description.
• Target identifiers: prefer IDs for stability, names work when unambiguous.

Snapshot Layout

.inconvo/
  agents/
    .slug-map.yaml
    <agent-slug>/
      agent.yaml                  # contains agentId
      user-context.yaml           # fields + status
      shareable-connections.yaml
      connections/
        <connection-slug>/
          connection.yaml         # reference only — includes description + snapshotPath
  connections/
    .slug-map.yaml
    <connection-slug>/
      connection.yaml             # contains connectionId + description
      tables/
        .slug-map.yaml
        <table-slug>.yaml         # full table snapshot: columns, relations, computed, condition, policy

All files are auto-generated. Read them for IDs and current state; never edit directly.

Sync Terms

• Post-mutation sync: automatic refresh of local .inconvo/ files after a successful mutation.
• model pull: rebuild local snapshots from the platform.
• connection sync: ask the platform to re-introspect a connection's database schema. Follow with model pull when you need updated local files.

Standard Workflow

1. Read .inconvo/ YAML files to understand current state and collect IDs.
2. Read code context (schema, routes, UI) to understand intended semantics.
3. Plan all mutations, group independent ones for parallel execution.
4. Run mutations. Use --dry-run --json when target resolution is uncertain. For many independent mutations, add --no-sync to each command and run inconvo model pull once at the end.
5. Verify the synced YAML files reflect expected changes.
6. If sync fails, run inconvo model pull --agent <agentId>.

Command Discovery

npx inconvo@latest model --help
npx inconvo@latest model <group> --help
npx inconvo@latest model action schema --json   # lists all valid action names
npx inconvo@latest connection --help

Full Mutation Reference

Connection Metadata

Use connection commands for database-level metadata, not semantic-model changes:

# Read current connection metadata (description maps to platform "context")
npx inconvo@latest connection get \
  --agent <agentId> --connection <connectionId> --json

# Set the description
npx inconvo@latest connection update \
  --agent <agentId> --connection <connectionId> \
  --description "Sales warehouse used for BI reporting" --json

# Clear the description
npx inconvo@latest connection update \
  --agent <agentId> --connection <connectionId> \
  --clear-description --json

connection update refreshes the local .inconvo/ snapshot for that connection. It does not perform a remote DB rescan; connection sync does that.

Computed Column AST Format

The --ast flag takes a JSON string. Node types and their shapes:

{ "type": "column",    "name": "<columnName>" }
{ "type": "value",     "value": 42 }
{ "type": "function",  "name": "ABS", "arguments": [<node>] }
{ "type": "operation", "operator": "+"|"-"|"*"|"/"|"%", "operands": [<node>, <node>] }
{ "type": "brackets",  "expression": <node> }

Example — (subtotal - discount) + tax:

npx inconvo@latest model computed create \
  --agent <agentId> --connection <connectionId> \
  --table orders --name "total" \
  --ast '{"type":"operation","operator":"+","operands":[{"type":"brackets","expression":{"type":"operation","operator":"-","operands":[{"type":"column","name":"subtotal"},{"type":"column","name":"discount"}]}},{"type":"column","name":"tax"}]}' \
  --unit USD --json

Note: --dry-run does NOT validate the AST schema — it only resolves the target entity and shows what would be sent. The API validates the AST and returns a detailed Zod error listing valid node shapes if it's wrong.

Relations Workflow

FK relations defined in the database schema are auto-introspected by the platform and should appear in table YAML under outwardRelations with source: FK on the first pull. No manual steps should be required.

Only create manual relations when no FK constraint exists in the DB (e.g. soft references, denormalised keys, or cross-database joins).

Check current relation state:

grep -E "source: MANUAL|source: FK|^  - id: relation_|^    name:" \
  .inconvo/connections/<slug>/tables/<table>.yaml

If FK relations are missing after a pull

Before creating manual relations, ask the user to confirm:

1. Do the FK constraints actually exist in the database? Check with the user or inspect the schema — if there are no FK constraints, that explains the absence.
2. Does the Inconvo DB user have access to information_schema? FK introspection requires read access to information_schema.key_column_usage and information_schema.referential_constraints. If this permission is missing, run a connection sync after granting it and then pull again.

Only fall back to manual relations if FKs genuinely don't exist in the schema.

Semantic Model Content Guidelines

Prefer fewer, higher-signal semantics over broad coverage. Default to preserving existing semantics; only mutate entries that are clearly missing, wrong, or materially improved by the code context.

Before adding or changing table context or column notes, ask: "Does this add non-obvious business meaning that is not already captured by the schema, relations, units, renames, computed columns, or existing notes?" If not, skip it.

Keeping each layer focused prevents duplication and improves model quality:

• Do not add notes just to fill blank fields. Broad annotation coverage is worse than a smaller set of precise semantics.
• Do not restate ownership or tenant scoping in notes or table context when relations and row-level conditions already express it.
• Preserve existing good semantics. Change only what is clearly improved by the code context.

Multi-Tenancy Pattern

For apps that scope all data by a tenant/organisation ID:

# 1. Add the tenant field to user-context
npx inconvo@latest model user-context add-field \
  --agent <agentId> --key organisationId --type NUMBER --no-sync --json

# 2. Enable user-context
npx inconvo@latest model user-context set-status \
  --agent <agentId> --status ENABLED --no-sync --json

# 3. Set condition on every tenant-scoped table (run in parallel)
npx inconvo@latest model condition set \
  --agent <agentId> --connection <connectionId> \
  --table <table> --column organisation_id --field organisationId --no-sync --json

# 4. Pull once at the end
npx inconvo@latest model pull --agent <agentId> --json

Conditions require user-context to be ENABLED to take effect. The order of add-field / set-status / condition set does not matter as long as status is ENABLED before queries run.

Table Access Decision Guide

JOINABLE is only useful when there is at least one QUERYABLE table with a relation path to it. A JOINABLE table with no reachable path is effectively OFF.

High-Confidence Patterns

Bulk table setup (run in parallel with --no-sync, then pull once)

npx inconvo@latest model table set-access \
  --agent <agentId> --connection <connectionId> \
  --table <table> --access QUERYABLE --no-sync --json

npx inconvo@latest model table set-context \
  --agent <agentId> --connection <connectionId> \
  --table <table> --context "What this table is and when to use it." --no-sync --json

# After all mutations complete:
npx inconvo@latest model pull --agent <agentId> --json

Column updates

# Rename + notes in one command
npx inconvo@latest model column update \
  --agent <agentId> --connection <connectionId> \
  --table <table> --column <column> \
  --rename "display name" --notes "What this column means." --json

# Hide sensitive column
npx inconvo@latest model column update \
  --agent <agentId> --connection <connectionId> \
  --table <table> --column password --selected false --json

# Set currency unit
npx inconvo@latest model column set-unit \
  --agent <agentId> --connection <connectionId> \
  --table <table> --column price --unit USD --json

Manual relation (fallback when no FK)

npx inconvo@latest model relation manual create \
  --agent <agentId> --connection <connectionId> \
  --source-table <table> --target-table <table> \
  --name "relationName" --is-list false \
  --pair "source_col:target_col" --json

Pull for a specific connection

npx inconvo@latest model pull \
  --agent <agentId> --connection <connectionId> --json

Resolution Rules

The CLI resolves --table, --column, --relation, --field in this order:

1. Exact ID match
2. Exact name match
3. Case-insensitive unique name match

If ambiguous (multiple matches) or not found — fail fast and use the explicit ID from the YAML file.

Error Recovery

Done Criteria

• All remote mutations executed via CLI.
• Local .inconvo/ snapshot auto-synced after each mutation (or synced once at end if --no-sync was used).
• No manual edits to generated YAML files.
• Table contexts describe purpose only — no column-level details.
• Column notes describe the specific column only — no table-level details.
• Derived metrics live in computed columns; not repeated in input column notes.