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

magus-query

Search the knowledge graph, and retrieve a run's output or journal by id

Synopsis

magus query <terms> [flags]

Description

Ask the workspace what it knows. query resolves terms to nodes in the knowledge graph and returns the ranked matches plus the induced subgraph around them, collected up to a node budget. Its siblings explain and path read the same graph: explain shows one node's context, path connects two nodes.

Terms are free text plus field matchers, and they compose: kind=spell, project=pkg/foo, relation=uses, id=build, exclusion with kind!=op, and a regex with id=~build$. A bare word matches names and documentation. The : grammar (kind:spell, -kind:op) still parses as a compat alias.

query is also the retrieval verb for the two ids magus prints, each an EXPLICIT subcommand rather than a shape-routed positional, so a search term can never collide with an id:

output <ref> One target run's captured output, by the output ref shown when the target ran (out1a2b3c). The default prints the exact bytes, so it pipes anywhere. --identity shows the run's identity instead - descriptor, lineage, cache key, and the digests of the key's component classes, which is the machine-comparable half of a works-on-my-machine report. --attempts lists the ref's stored attempts, --publish uploads the output to the remote cache as a signed bundle, and --open hands the bytes to the browser log viewer in a URL fragment (delivered privately; never uploaded). invocation <id> One run's journal, by the invocation id shown as inv: in query output <ref> --identity. --secrets narrows it to the credential reads - which references the run reached for and through which provider, never the value - which is how an audit answers "what did this run touch". Run logs are trimmed to a cap by the daemon's RotateLogs job, so this answers for recent runs rather than forever.

The graph is cache-backed under <cache>/knowledge and only shards whose sources changed are rebuilt, so a query is cheap to repeat; --refresh forces a full rebuild.

Options

--attempts
output <ref>: list the ref's stored attempts (newest first)
--budget int
Max nodes in the returned neighborhood (default 50)
--global
Query across the workspaces registered in config (knowledge.workspaces); IDs are namespaced by workspace
--identity
output <ref>: show the run's identity - descriptor, lineage, cache key, component digests
--kind string
Restrict matches to these node kinds (comma-separated)
--open
output <ref>: open the captured output in the browser log viewer (delivered privately)
--print
With --open, print the viewer URL instead of launching a browser
--publish
output <ref>: upload this run's output to the remote cache as a signed bundle
--refresh
Force a full graph rebuild before querying
--secrets
invocation <id>: list only the credential reads (reference and provider, never the value)
--url string (default: https://eli.gladman.cc/magus/console/logs/)
With --open, base URL of the log viewer page (override for a self-hosted mirror)

Subcommands

output
Retrieve one target run's captured output by output ref
invocation
Read one run's journal by invocation id (--secrets for the credential reads)

Examples

Find a spell by name

magus query kind=spell go

What uses this target

magus query relation=uses id=build

Everything but ops

magus query docker kind!=op

Print a run's captured output

magus query output out1a2b3c

Compare a run's cache key

magus query output out1a2b3c --identity

Audit a run's credential reads

magus query invocation invmsm3vcou1 --secrets

See Also

magus(1), magus-ls(1), magus-describe(1), magus-run(1), magus-x(1), magus-where(1), magus-affected(1), magus-graph(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. magus graphEmit the project dependency DAG, export the knowledge graph for external graph tools, and report the graph's shape (god nodes, orphans, doc coverage). Cache modelHow magus computes a content-addressed cache key from a target's declared inputs, replays outputs on a hit without rerunning the body, and stores it all as plain files under .magus.
generatedinternal/cli/registry.goclimagus queryqueryknowledge graphsearchoutputreferenceinvocationjournalaudit
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.

Buzz

The language magusfiles are written in (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.

Remote cache

A CI-only backend that shares content-addressed artifacts across runners: a cold machine replays a build another runner already did instead of rebuilding. Every remote artifact must be signed by a trusted key. See remote.

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.

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.