magus v0.3.0 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
3 min read

magus-graph

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

Synopsis

magus graph <deps|export|stats|open> [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):

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. 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. insight report embeds this section. open Open the workspace's knowledge graph (or target dependency graph with --targets) in the hosted, interactive Graph Explorer. The graph is delivered privately: by default it 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).

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)
--global
Union the workspaces registered in config (knowledge.workspaces); node IDs are namespaced by workspace
--refresh
Force a full graph rebuild before exporting
--select string
Export only the neighborhood of a query (same grammar as magus query); required for -o dot and -o mermaid

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

graph open options

--print
Print the explorer URL to stdout instead of opening a browser
--refresh
Force a full graph rebuild before opening (knowledge graph only)
--serve
Hand the graph to the page from an ephemeral loopback server instead of a URL fragment (no size limit; incompatible with --targets)
--targets
Open the target dependency graph instead of the knowledge graph; pass a project path as a positional argument to scope to one project
--url string (default: https://eli.gladman.cc/magus/console/graph/)
Base URL of the Graph Explorer page (override for a self-hosted mirror)

Subcommands

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
open
Open the workspace graph in the hosted Graph Explorer (data never leaves your machine)

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 open

Open target dependency graph

magus graph open --targets

Scope target graph to one project

magus graph open --targets docs

Print the URL instead of opening

magus graph 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-insight(1), magus-watch(1), magus-status(1), magus-doctor(1), magus-config(1), magus-server(1), magus-completion(1), magus-man(1), magus-init(1), magus-self(1), magus-version(1)

ManpagePages in this section. 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. magus-queryQuery the magus knowledge graph to find and relate entities (projects, targets, spells, ops, charms, modules, diagnostics, docs). magus DocumentationThe magus documentation hub covering install, targets, spells, charms, operations, engines, remote caching, MCP, telemetry, and the interactive playground.
auto-generatedclimagus graphgraphknowledge graphdependency graphexportgraphml
Last updated (a59e71c9)
Earlier changes on this page (2)

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.

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.

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.

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). See insight.

Conventions

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