NPM client

@igentify/helix-flowgraph is the integrator CLI and library for Helix Flowgraph: query the latest workspace graph and orchestrate scans from scripts or agents.

Install

Add to .npmrc (project or ~/.npmrc):

@igentify:registry=https://igentify-488414467642.d.codeartifact.us-east-1.amazonaws.com/npm/npm/

Then:

npm install @igentify/helix-flowgraph

Authentication uses the Query API key in SSM (/helix/flowgraph/api-key) for cloud commands. The CLI loads it with your AWS credentials (AWS_PROFILE or --profile). Default API host: https://helix-flow.igentify.in.

Local mode (--local) runs bundled ingest + helix-agent on filesystem paths — no AWS, no SSM, no Step Functions, no helix-flowgraph clone. npx / npm install is sufficient for both cloud and local; the same CLI commands apply (query, scan, list).

Surface	Cloud (default)	Local (--local)
query features	✓	✓
query unbridged	✓	✓
query repo=…	✓	✓ (with AI summaries when scan has ai/)
list / scan list	✓	— (cloud scan history)
scan start	✓ (GitHub workspace)	✓ (--repo-path, bundled ingest + AI)
scan status / watch / cancel	✓	— (local scans are synchronous)
query … --scan-id	✓ (any READY scan)	✓ (./scans/<id>/)
query … --workspace-id	✓ (that workspace’s LATEST)	—

Run npx @igentify/helix-flowgraph --help for the full command reference.

Local mode (filesystem scan + query)

Scan a checkout on disk and query the resulting graph without touching AWS:

# npx only — no helix-flowgraph clone required
npx @igentify/helix-flowgraph scan start --local \
  --repo-path ~/code/igentify/report-builder-service

npx @igentify/helix-flowgraph query features --local
npx @igentify/helix-flowgraph query repo=report-builder-service --local
npx @igentify/helix-flowgraph query unbridged --local

What	Behavior
Output	scans/<scanId>/ under your project cwd (default ./scans); updates scans/latest symlink
Default pipeline	Feature YAML binding + full helix-agent AI (same stages as cloud, local disk only)
Speed	Ingest ~seconds; AI minutes–hours depending on repo size and LLM provider
Opt out	--technical-only — AST graph only (no features, no AI)
Cloud	No S3 upload, no scan list entry

Local options

Option	Purpose
--local	Local ingest (scan) or in-process graph read (query)
--repo-path <path>	Local repository root (scan start --local; repeat for multiple)
--out <dir>	Scans output base (default ./scans)
--technical-only	AST-only: skip feature YAML binding and all AI passes
--no-update-latest	Do not symlink scans/latest after scan
--graph-path <path>	Override graph file for local query
--scan-root <path>	Scan folder (AI artifacts) for local query
--scan-id <id>	Query a specific READY scan (cloud S3 or local ./scans/<id>/)
--workspace-id <id>	Cloud: query that workspace’s LATEST READY scan (default: canonical workspace)

Local environment variables

Variable	Purpose
HELIX_GRAPH_PATH	Graph file for query --local (default: scans/latest/reports/technical-graph.json)
HELIX_SCAN_ROOT	Scan folder for AI artifact paths
HELIX_SCANS_DIR	Override scans output directory
HELIX_LOCAL=1	Same as --local

import { startLocalScan, queryFeatures, queryRepos } from "@igentify/helix-flowgraph";

const result = await startLocalScan({
  repoPaths: ["~/code/igentify/report-builder-service"],
});
// result: { local: true, scanId, status: "READY", graphPath, scanRoot, runtime: "bundle", ... }
await queryRepos("report-builder-service", { local: true });

Query commands

Read data from a READY scan graph (default: canonical workspace LATEST; override with --scan-id or --workspace-id).

Command	What it does
query features	List Feature nodes (id, name, flowKey). Use to discover feature ids before opening a feature neighbourhood.
query unbridged	List backend ApiEndpoint nodes with no FE→BE bridge — no CALLS_REMOTE chain from a frontend client call. Same set as the UI “Unbridged endpoints” view.
query repo=<repoKey>	Repo subgraph: nodes, edges, and AI summaries on each (data.aiSummary).
query repo=a,b,c	Combined subgraph for multiple repos (comma-separated keys).
query … --local	Same commands against scans/latest (or HELIX_GRAPH_PATH); no AWS.
query … --scan-id <id>	Pin to one READY scan (historical graph, pre-feature commit scan, etc.).
query … --workspace-id <id>	Pin to LATEST READY for an ephemeral or alternate workspace.

npx @igentify/helix-flowgraph query features
npx @igentify/helix-flowgraph query features --local
npx @igentify/helix-flowgraph query features --scan-id 01KX0JWPM83J
npx @igentify/helix-flowgraph query unbridged
npx @igentify/helix-flowgraph query repo=ng-access-service
npx @igentify/helix-flowgraph query repo=ng-access-service --scan-id 01KX0JWPM83J
npx @igentify/helix-flowgraph query repo=ng-access-service --local
npx @igentify/helix-flowgraph query repo=ng-access-service,ng-work-space-ui

Querying a previous scan or branch

A branch name is not a query parameter — scan the commit first, then query by scanId:

import { startScan, watchScan, queryFeatures, queryRepos } from "@igentify/helix-flowgraph";

// Scan pre-feature commit into an ephemeral workspace
const { scanId, workspaceId } = await startScan({
  workspaceId: "pre-feature-enrollments",
  repos: [{
    repoKey: "ng-access-service",
    fullName: "igentify/ng-access-service",
    commit: "abc123def456", // pre-feature SHA
  }],
});
await watchScan(scanId);

// Query that scan (not canonical LATEST)
const { features } = await queryFeatures({ scanId });
await queryRepos("ng-access-service", { scanId });

// Or: latest READY in that workspace only
await queryFeatures({ workspaceId });

npx @igentify/helix-flowgraph scan list --workspace-id pre-feature-enrollments --completed
npx @igentify/helix-flowgraph query features --scan-id 01KX...

Scan commands

Start and monitor the ingest + AI pipeline (clone → AST → merge → AI enrichment → READY).

Command	What it does
list / scan list	List workspace scans, newest first. Default: today only (local midnight → now). Response includes from / to bounds applied.
list --from <dt>	Lower bound on startedAt (ISO 8601). --to defaults to now.
list --to <dt>	Upper bound; --from defaults to start of that local calendar day.
list --from <dt> --to <dt>	Explicit window (e.g. --from 2026-07-01 --to 2026-07-08).
list --completed	Same, but only READY (successful) scans.
scan start --local --repo-path <path>	Local ingest on a filesystem checkout. Writes scans/<scanId>/, updates scans/latest. No AWS. Bundled in npm package (no clone required).
scan start --repo <key>	Start a single-repo rescan. Seeds merge inputs and AI artifacts from the latest READY scan for other repos, then re-runs workspace feature synthesis/insights/labels.
scan start	Scan the full workspace roster (all configured repos).
scan status <scanId>	Current state: overall status, progressPercent (0–100), per-repo stage/status, branch, commit SHA, execution ARN.
scan watch <scanId>	Poll until READY or FAILED; prints JSON on each change (includes progressPercent). Exit code 1 on failure.
scan cancel <scanId>	Stop the Step Functions execution and mark the scan cancelled.

npx @igentify/helix-flowgraph list
npx @igentify/helix-flowgraph list --from 2026-07-01
npx @igentify/helix-flowgraph list --completed
npx @igentify/helix-flowgraph scan start --repo ng-access-service
npx @igentify/helix-flowgraph scan start --local --repo-path ~/code/igentify/report-builder-service
npx @igentify/helix-flowgraph query repo=report-builder-service --local
npx @igentify/helix-flowgraph scan status 01JABC...
npx @igentify/helix-flowgraph scan watch 01JABC...
npx @igentify/helix-flowgraph scan cancel 01JABC...

Common options

Option	Purpose
--local	Local filesystem scan or in-process query (no AWS)
--scan-id <id>	Query a specific READY scan
--workspace-id <id>	Query LATEST READY for a workspace (cloud)
--repo-path <path>	With scan start --local: local repository root
--profile <name>	AWS profile for SSM API key lookup (cloud only)
--region <name>	AWS region (default us-east-1)
--base-url <url>	Override API base URL (cloud only)
--interval <ms>	Poll interval for scan watch (default 5000)
--compact	Minified JSON on stdout

Library — query

Typed helpers wrap the Query REST API. Request body schemas live in shared/src/queries.ts; each helper below maps to a route handler in backend/src/routes.ts.

import {
  queryFeatures,
  queryFeature,
  queryRepos,
  queryUnbridged,
  queryCompareFeatures,
  queryImplementationAnchor,
  queryEndpointQa,
  queryEndpointPotentialIssues,
  queryEndpointQaFe,
  queryEndpointPotentialIssuesFe,
  queryFeatureInsights,
  queryFeatureDisplayTitles,
  queryImpact,
  queryNode,
  queryHealth,
} from "@igentify/helix-flowgraph";

// Feature catalogue from latest READY scan
const { features, scanId } = await queryFeatures();
await queryFeatures({ local: true }); // scans/latest on disk
await queryFeatures({ scanId: "01KX…" }); // historical / branch scan
await queryFeatures({ workspaceId: "pre-feature-enrollments" });

// One feature neighbourhood
await queryFeature("feature:…");

// Endpoints missing a FE→BE bridge
const { endpoints, counts } = await queryUnbridged();

// Repo slice with AI summaries
await queryRepos("ng-access-service");
await queryRepos(["ng-access-service", "ng-work-space-ui"]);

// Shared vs unique nodes between two features
await queryCompareFeatures("feature:…", "feature:…");

// Heuristic “where to implement?” anchor lookup
await queryImplementationAnchor({ featureQuery: "searchUsers" });

// AI artifacts (lazy S3 read — 404 or `{ error }` when not generated yet)
await queryEndpointQa("repo:…|ApiEndpoint:…");
await queryEndpointPotentialIssues("repo:…|ApiEndpoint:…");
await queryEndpointQaFe("repo:…|ApiClientCall:…");
await queryEndpointPotentialIssuesFe("repo:…|ApiClientCall:…");
await queryFeatureInsights("feature:…");
await queryFeatureDisplayTitles();

// Graph utilities
await queryImpact("feature:…");
await queryNode("feature:…");

// Liveness
await queryHealth();

For routes without a named helper yet (/query/technical-graph inline delivery), use queryGraph("/query/…") (GET) or call the REST API directly (POST).

Verify exports after install:

node -e "import('@igentify/helix-flowgraph').then(m=>console.log(typeof m.queryFeatureInsights))"
# expect: function

Library — scan

import {
  startScan,
  startLocalScan,
  listScans,
  getScanStatus,
  watchScan,
  cancelScan,
} from "@igentify/helix-flowgraph";

const { scans, from, to } = await listScans({ completed: true });
await listScans({ from: "2026-07-01T00:00:00Z", to: "2026-07-08T23:59:59Z" });

const { scanId } = await startScan({ repoKey: "ng-access-service" });

// Scan a specific commit (POST body — use library, not CLI --repo alone)
await startScan({
  workspaceId: "my-experiment",
  repos: [{ repoKey: "ng-access-service", fullName: "igentify/ng-access-service", commit: "abc123" }],
});

// Local filesystem scan (no AWS, no clone)
await startLocalScan({
  repoPaths: ["~/code/igentify/report-builder-service"],
});

await watchScan(scanId, {
  pollIntervalMs: 5000,
  onUpdate: (run) => console.log(run.status, run.repos),
});

const final = await getScanStatus(scanId);
await cancelScan(scanId); // while running

REST endpoint details: Query REST API.