CLI Reference

The ai CLI is the primary interface for Apart Intelligence. Install it globally via npm:

npm install -g @apart-tech/apart-intelligence

Knowledge Management

ai add

Create a knowledge node.

ai add "Your content here"
ai add "Content" --type policy --title "PR Policy" --domain quality
ai add "Content" --status approved --by team-lead

Flag	Description
`--type <type>`	Node type (note, architecture, process, policy, decision)
`--title <title>`	Node title (auto-generated if omitted)
`-d, --domain <slug>`	Domain to assign to
`--status <status>`	Initial status (default: draft)
`--by <creator>`	Creator identifier

ai search

Hybrid semantic + keyword search.

ai search "deployment process"
ai search "security" --type policy --limit 5
ai search "api" --include-drafts --workspace eng

ai context

Assemble related knowledge via search + graph traversal.

ai context "incident response"
ai context "onboarding" --depth 2 --max-nodes 50
ai context "deployment" --workspace ops -f markdown

ai get

View a node and its edges. Accepts short ID prefixes.

ai get f69b06e0             # short prefix works
ai get f69b06e0 -f json    # full JSON output

Use --decrypt to view encrypted PII in its original form:

ai get f69b06e0 --decrypt   # decrypt PII fields

ai update

Update a node's content, title, type, or domain.

ai update <id> --title "New Title"
ai update <id> --content "Updated content"
ai update <id> --type architecture --domain architecture

ai delete

Delete a node or edge.

ai delete node <id>        # deletes node and its edges
ai delete edge <id>        # deletes a single edge

ai link

Create an edge between two nodes. Accepts short ID prefixes.

ai link <source> <target>
ai link <source> <target> --rel "depends-on" --weight 0.8

Lifecycle

ai drafts

List all draft nodes pending review.

ai status

Change a node's lifecycle status.

ai status <id> approved    # visible in search
ai status <id> archived    # hidden but preserved
ai status <id> reviewed    # mark as reviewed

Organization

ai domains

ai domains seed            # populate default taxonomy
ai domains list            # show hierarchy
ai domains show technology # details for one domain

ai workspace

ai workspace create eng --description "Engineering" \
  --domains "architecture,development" \
  --types "architecture,policy,module,function,method,class"

ai workspace use eng       # activate filter
ai workspace clear         # deactivate
ai workspace list          # show all workspaces
ai workspace show eng      # details
ai workspace export eng    # export as markdown
ai workspace delete eng

Codebase Integration

ai codebase init

Interactive setup for Claude Code skills, GitHub Actions workflows, and CI/CD in the current project. See the CI/CD Workflows guide for full details.

cd ~/my-project
ai codebase init           # interactive feature selection
ai codebase init -y        # non-interactive (skills + rules only)

Features available during init:

Feature	Description
Claude Code skills	`/capture`, `/document`, `/sync` slash commands
Apart Intelligence rules	Context rules for Claude Code
PR auto-review	GitHub Action that reviews every PR
Knowledge sync on merge	GitHub Action that syncs your graph when PRs merge
Slash commands	`/ai-review`, `/ai-implement` in PR comments
Generate CLAUDE.md	Auto-detect stack and generate project context

ai codebase prompts

Generate tailored workflow prompts by running an AI agent that analyzes your codebase. Can be run after init or re-run at any time to update prompts.

ai codebase prompts                              # interactive
ai codebase prompts "security, multi-tenancy"    # with priorities

ai codebase status

Show which skills, rules, workflows, and other features are installed.

ai codebase status

ai map

Map source code into the knowledge graph with AST-based function extraction.

ai map .                                        # map current directory
ai map . --status approved --root-node <id>     # approved, connected to root
ai map . --dry-run                               # preview only
ai map . --exclude "test,fixtures"               # skip patterns

Flag	Description
`--root-node <id>`	Connect modules to this node via "contains" edges
`--status <status>`	Node status (default: draft). Use "approved" for immediate searchability
`--dry-run`	Analyze without creating nodes
`--exclude <patterns>`	Comma-separated patterns to skip
`-y`	Skip confirmation prompt

See the Codebase Mapping guide for the full workflow.

ai import

Bulk import nodes and edges from a JSON file. Uses batch embeddings and bulk SQL inserts for performance.

ai import data.json                          # import with confirmation
ai import data.json -y                       # skip confirmation
ai import data.json --dry-run                # validate without importing
ai import data.json -d engineering           # assign to a domain
ai import data.json --by data-team -f json   # custom creator, JSON output

Flag	Description
`--by <creator>`	Creator identifier (default: "import")
`-d, --domain <slug>`	Domain to assign all imported nodes to
`--dry-run`	Validate the file without importing
`-y`	Skip confirmation prompt

The import file is a JSON file with nodes and optional edges arrays:

{
  "nodes": [
    {
      "ref": "n1",
      "type": "concept",
      "title": "AI Safety",
      "content": "Overview of AI safety research.",
      "metadata": { "source": "manual" },
      "status": "draft"
    },
    {
      "ref": "n2",
      "type": "concept",
      "title": "Alignment",
      "content": "Technical approaches to AI alignment."
    }
  ],
  "edges": [
    { "source": "n1", "target": "n2", "relationshipType": "relates_to" },
    { "source": "n1", "target": "abc123-existing-uuid", "relationshipType": "part_of" }
  ]
}

Node field	Required	Description
`ref`	No	Local ID for referencing in edges
`type`	Yes	Node type
`title`	Yes	Node title (must be unique)
`content`	Yes	Node content
`metadata`	No	Arbitrary JSON metadata
`status`	No	draft, reviewed, approved, archived (default: draft)

Edge source and target can be a ref from the file or an existing node UUID. Nodes with duplicate titles are skipped with a warning.

PII Protection

ai pii show

Show PII policy for your organization.

ai pii show

ai pii set

Configure PII policy.

ai pii set encrypt                          # enable encryption
ai pii set encrypt --allow-bypass             # allow per-request bypass
ai pii set encrypt --allowed-types email      # allow emails unencrypted
ai pii set detect-warn                        # detect only, don't encrypt
ai pii set disabled                           # disable PII processing

ai pii test

Scan text for PII without storing anything.

ai pii test "Contact john@example.com or call (555) 123-4567"

ai pii delete

Remove PII policy. Warning: encrypted PII becomes unrecoverable.

ai pii delete

Analysis

ai types                   # node and edge types in use
ai health                  # comprehensive graph health report
ai orphans                 # find unconnected nodes
ai duplicates              # find near-duplicate nodes
ai islands                 # detect disconnected clusters
ai suggest-links           # suggest missing connections
ai validate                # validate edge integrity
ai normalize               # analyze relationship type vocabulary
ai graph                   # interactive HTML visualization

AI Agents

Run autonomous, graph-aware tasks in the cloud. See the AI Agents guide for full details.

ai agent "Research X and add findings"          # run a task (default: researcher)
ai agent "Plan feature X" --type planner         # use a specific agent type
ai agent "Review PR #42" --type reviewer         # code review agent
ai agent "Analyze graph health" -m opus          # use specific model
ai agent "Update stale nodes" --no-wait          # fire and forget

ai agent types                                   # list available agent types

ai agent register                                # use your Claude subscription
ai agent unregister                              # remove personal tokens

ai agent secrets set --github-pat <token>        # set GitHub PAT for dev agents
ai agent secrets set --db crm --db-type postgres <url>  # add database connection
ai agent secrets show                            # check configured secrets
ai agent secrets delete                          # remove all secrets

ai agent config                                  # show org config
ai agent config set                              # set org API keys + template
ai agent config delete                           # remove org config

ai agent runs                                    # list recent runs
ai agent runs --status completed --type developer  # filter by status and type
ai agent status <run-id>                         # check a specific run

Authentication

ai init                    # setup wizard
ai login                   # interactive login (browser SSO or API key)
ai login --sso             # browser login via Auth0
ai login --key <key>       # authenticate with API key
ai logout                  # clear credentials
ai whoami                  # check connection & current org

Organizations

Manage multi-organization membership. Requires browser login (ai login --sso).

ai org list                # list organizations you belong to
ai org switch              # interactive org picker
ai org switch <slug>       # switch by slug
ai org current             # show active organization
ai org claim               # claim ownership (requires API key + SSO)

Invites

Invite team members to your organization. Requires admin or owner role.

ai invite send <email>              # invite as member
ai invite send <email> --role admin # invite as admin
ai invite list                      # list pending invites
ai invite revoke <id>               # revoke a pending invite
ai invite accept <token>            # accept an invite

Output Formats

Every command supports -f json for scripting:

ai search "api" -f json | jq '.[].node.title'
ai context "onboarding" -f json | jq '.nodes | length'
ai types -f json