magus v0.4.2 is out. See what's new
¶ View generated markdown
5 min read

magus-graph

The workspace's graphs as objects: deps, export, stats

Synopsis

magus graph <build|deps|export|stats|diff> [flags]

Description

The workspace's graphs as objects: emit, export, and measure them. The query, explain, and path verbs read the knowledge graph; magus graph is the home of the graph itself.

Subcommands (the first argument):

build Rebuild the knowledge graph now, reindexing code symbols first (runs each symbol-capable project's scip op) unless --no-symbols. The daemon does this automatically in the background; this is the manual trigger, after a branch switch or when the daemon is not running. deps The project dependency DAG. A trailing list of project paths roots the graph; -o selects text, json, yaml, dot, mermaid, or tree. The same view scoped to a run is available as magus run <target> --graph and magus affected <target> --graph. export The merged knowledge graph: the deterministic, cache-backed graph of the magus domain (projects, targets, spells, ops, charms, modules, methods, diagnostics, docs, buzz sources). -o json emits the node-link form; -o graphml emits GraphML. External graph viewers (Gephi, yEd) read both directly. --select "<terms>" narrows the export to a query's neighborhood (same engine as magus query); -o dot and -o mermaid render only with --select, since the full graph has too many nodes to lay out. The graph is cache-backed under <cache>/knowledge; only shards whose sources changed are rebuilt. --open sends it to the hosted, interactive Graph Explorer instead of stdout (there is no separate "open" subcommand): by default the graph rides in the URL fragment (#data=...), which browsers never send to a server; --serve instead hands it from an ephemeral 127.0.0.1 loopback server (no size limit), and --targets opens the target dependency graph instead of the knowledge graph. stats The graph's shape: god nodes (the most connected spells, modules, targets - where structural risk concentrates), orphans (docs that document nothing, spells no target uses), and doc coverage (the share of diagnostics, spells, and modules with a doc). --kind scopes every section to one node kind. The VCS-history lenses (hotspots, affinity, ownership, trend, unreferenced) are a separate view, served by the magus_insight MCP tool and the console's Insight page - not by this command. diff Nodes and edges added, removed, or changed relative to a baseline export or a git revision (--rev): the PR-review blast-radius artifact, emit as json or markdown for a CI comment.

graph build options

--no-symbols
Rebuild the domain graph only; do not reindex code symbols

graph deps options

--depth int
Cap displayed depth (0 = unlimited)
--spell string
Only projects driven by this spell
--target string
Target whose duration history annotates nodes (default: build)
--upstream
Show dependents instead of dependencies

graph export options

--budget int (default: 50)
Node budget for --select (how many nodes the neighborhood may collect)
--follow
With --open: keep the explorer updating from the running daemon instead of showing a snapshot (needs magus server start)
--global
Union the workspaces registered in config (knowledge.workspaces); node IDs are namespaced by workspace
--open
Deliver the graph to the hosted Graph Explorer instead of stdout; it never leaves your machine
--print
With --open: print the explorer URL to stdout instead of launching a browser
--refresh
Force a full graph rebuild before exporting
--reproducible
Omit everything that is not a function of the source tree (locally observed runtime attrs, git history), so two checkouts of one commit export identical bytes
--select string
Export only the neighborhood of a query (same grammar as magus query); required for -o dot and -o mermaid
--serve
With --open: hand the graph to the page from an ephemeral loopback server instead of a URL fragment (no size limit; incompatible with --targets)
--static
Deprecated alias for --reproducible
--targets
With --open: open the target dependency graph instead of the knowledge graph; pass a project path to scope it
--url string (default: https://eli.gladman.cc/magus/console/graph/)
With --open: base URL of the Graph Explorer page (override for a self-hosted mirror)

graph stats options

--global
Union the workspaces registered in config (knowledge.workspaces) before computing stats
--kind string
Scope every section to one node kind (spell, target, doc, ...)
--refresh
Force a full graph rebuild first
--symbols
Include the lazily-loaded symbol shards in the stats; excluded by default because they can dwarf the domain graph

graph diff options

--global
Diff the global (all-workspaces) graph; match this to how the baseline was exported
--refresh
Force a full graph rebuild of the current graph before diffing
--rev string
Diff against a git revision (e.g. HEAD~1, main) instead of an export file

Subcommands

build
Rebuild the knowledge graph now, reindexing code symbols first
deps
Emit the project dependency DAG (text, json, yaml, dot, mermaid, tree)
export
Export the merged knowledge graph (json node-link or graphml)
stats
Report the knowledge graph's shape: god nodes, orphans, doc coverage
diff
Nodes/edges added, removed, or changed vs a baseline export or --rev; PR blast-radius

Examples

Project DAG as Mermaid

magus graph deps -o mermaid

DAG rooted at one project, dependents up

magus graph deps pkg/api --upstream

Knowledge graph for an external viewer

magus graph export -o json > graph.json

GraphML for Gephi or yEd

magus graph export -o graphml > graph.graphml

A query's neighborhood as Mermaid

magus graph export --select 'kind=spell go' -o mermaid

Where structural risk concentrates

magus graph stats

Doc coverage for spells only

magus graph stats --kind spell

Open knowledge graph in browser

magus graph export --open

Open target dependency graph

magus graph export --open --targets

Scope target graph to one project

magus graph export --open --targets docs

Print the URL instead of opening

magus graph export --open --targets --print

See Also

magus(1), magus-ls(1), magus-describe(1), magus-run(1), magus-x(1), magus-where(1), magus-affected(1), magus-query(1), magus-explain(1), magus-path(1), magus-refs(1), magus-watch(1), magus-events(1), magus-status(1), magus-clean(1), magus-vcs(1), magus-doctor(1), magus-config(1), magus-session(1), magus-memory(1), magus-notes(1), magus-diff(1), magus-server(1), magus-mcp(1), magus-buzz(1), magus-completion(1), magus-man(1), magus-init(1), magus-agent(1), magus-self(1), magus-version(1)

ManpagePages in this section. ChangelogEvery released change to magus, newest first, in Keep a Changelog format. Generated from releases/*.yaml. Knowledge graphThe knowledge graph is a deterministic, cache-backed graph of the magus domain - projects, targets, spells, ops, charms, modules, diagnostics, docs, and buzz sources - that agents and humans query instead of grepping. This page covers the schema, the verbs, the file layout, and how to point external graph tools at an export. The CLI in practiceThe magus subcommands you actually reach for, grouped by the question you are asking, with the quirks that are not obvious from the help text.
generatedinternal/cli/registry.goclimagus graphgraphknowledge graphdependency graphexportgraphml
Last updated (c92c1327)
Earlier changes on this page (7)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. See workspace.

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. See workspace.

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. See targets.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

Charm

An execution modifier attached with : (lint:rw) that changes how a target runs, not which one; the built-in rw flips a check-only target to mutate in place, and ci always strips it. See charms.

Module

A magus stdlib namespace a magusfile imports for host capabilities: filesystem, exec, vcs, and more. See the module reference.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Engine

The interpreter a magusfile runs on; magus embeds the Buzz engine. See engines.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. See cache.

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. See affected.

Daemon

The background magus host that owns shared state such as services and the warm knowledge graph. See daemon.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Snapshot

A point-in-time view of live state - the pool's occupancy or a tick of exported metrics - as opposed to accumulated history. See daemon.

Knowledge graph

The queryable graph of a workspace's spells, targets, docs, and code relationships; query it with magus query/explain/path. See knowledge.

MAGUS.md

The committed routing index at a workspace root, regenerated from the knowledge graph: it lists every node and points at the exact query for a given question, so it is the entry point an agent reads first. See knowledge.

Insight

The reports magus derives over the graph and history (hotspots, affinity, ownership, trend, volatility, unreferenced). See insight.

Hotspot

An insight lens: edit frequency times complexity, the prime refactoring targets. The project view heat-colors the dependency graph by churn; --files ranks individual files. See insight.

Affinity

An insight lens: projects that change together (temporal coupling). A pair that co-changes without either declaring a dependency on the other is a candidate architectural smell. See insight.

Ownership

An insight lens: author concentration - the primary author and their share, the distinct-author count (the bus factor), and abandonment. See insight.

Trend

An insight lens: the recent half of the window against the earlier half. A positive delta is a rising hotspot; a negative one is cooling. See insight.

Session

One magus process's recorded facts - the targets it finished, their outcomes, and the lease it acted as - kept in a repo-scoped store every worktree shares. magus session lists them; the store prunes itself by last-fact age.

Conventions

This page uses none of the site's convention markers. The full set is on the conventions page.