inconvoai/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: