Docs

CLI & API

codiluce start is all most people need. The other commands give you each step on its own, for scripts, CI or a shared server.

Commands

Command	What it does
`start [PATH]`	Detect, index, serve and open the map. PATH defaults to the current directory.
`init`	Detect applications and write the configuration. Keeps an existing configuration and graph.
`index`	Analyze the repository into the graph. Reuses the cache for applications that did not change.
`serve`	Serve the read-only API and the map for an existing index.
`inspect …`	Query the graph from the terminal, as JSON: summary, entities, entity, relations, relation, diagnostics.
`history index`	Index past commits of a branch into the history store.
`history status`	Show what history is indexed.
`annotate`	Describe the code with a language model, after a cost estimate.

Run them as npx codiluce <command>, codiluce <command> after a global install, or npm run codiluce -- <command> from a source checkout.

Common options

Option	Meaning
`--repo PATH`	The repository. Defaults to the current directory.
`--state-dir PATH`	Where the analysis lives. Defaults to <repo>/.codiluce.
`--port N`	Server port. start tries 4300 and then the next free one; 0 asks the system.
`--no-open`	start: print the URL instead of opening a browser.
`--no-cache`	Analyze everything again instead of replaying unchanged applications.
`--history-indexing`	Let the map index commits on demand. The only route that writes.
`--read-only`	serve: refuse on-demand history indexing, even with --history-indexing.
`--ui PATH \| none`	serve another build of the map, or only the API.

Step by step

$ npx codiluce init --repo /path/to/repository
$ npx codiluce index --repo /path/to/repository
$ npx codiluce inspect summary --repo /path/to/repository
$ npx codiluce serve --repo /path/to/repository --port 4300

index exits with 0 when no analyzer reported an error, 2 when parse or configuration errors were recorded (the graph is still written), and 1 for fatal failures. A failed run keeps the previous graph. Reindexing while serve runs is picked up within about 30 seconds, and the map offers a reload.

Inspect the graph

$ npx codiluce inspect entities --search /auth/login --type api_endpoint
$ npx codiluce inspect entities --type database_table
$ npx codiluce inspect diagnostics --code unresolved-http-call
$ npx codiluce inspect relations --id ID --direction outgoing --type handles

Lists are paginated (100 by default, 500 at most) and leave out evidence. Details of one entity or relation include all of its evidence. The graph is plain SQLite, so you can also query .codiluce/codiluce.db directly.

HTTP API

serve binds to loopback and is read-only: it opens the graph read-only and only accepts GET, except for on-demand history indexing when you allow it. Open /api for the full directory. The main routes:

GET /api/summary                         counts and diagnostics of the index
GET /api/entities?search=&type=          entity search (paginated)
GET /api/entities/:id/relations          relationships with evidence
GET /api/projection/flows?kind=page      every flow by entry point
GET /api/projection/impact/:id?depth=4   blast radius
GET /api/projection/steps/:id            what happens from here
GET /api/projection/coverage             coverage category of every file
GET /api/projection/families             data families
GET /api/history                         the timeline
GET /api/history/changes?snapshot=&compareTo=
GET /api/source?entity=ID                a bounded window of source

Projection, source and detail routes accept snapshot=ID and compareTo=ID to read any indexed commit. Source is addressed by entity, evidence or finding, never by path, and is limited to 400 lines per request.