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

magus-describe

Define a magus concept and list its entities

Synopsis

magus describe <noun> [<name>] [flags]

Description

Define a magus concept and list every entity of that kind. The noun is one of spell, charm, target, project, workspace, module, mcp-tool, tool, file, or graph; singular and plural are interchangeable. Pass a name after the noun to detail a single entity instead of listing them all. (The knowledge graph lives under magus graph: export for the merged graph, stats for its shape.)

The charm noun is the inverse of a target ref: "describe charm rw" lists every target that declares the rw charm and the argv edit each one makes, the transpose of the charms a single "describe target" lists.

For a target ref (e.g. "api:build", or ":test" for all projects) magus prints the fully-evaluated dispatch plan: the workspace-rooted source and output globs, the spells that fire, the charm-applied command, and any per-target policy. A target that composes others also prints a "chain" line naming them in invocation order (e.g. "generate -> lint -> build -> test"), read from the ctx.needs calls in the magusfile; a cross-project step reads as "project:target". It lists DIRECT steps only, so a step that itself composes is described by its own ref. Add a charm and --explain (e.g. "lint:rw --explain") to see each charm reshape the command one step at a time.

describe target options

--against ref
With --cache: diff the live key inputs against the stored lines behind an output `ref`
--cache
Show the live cache key, the ref a run would print, the component classes behind it, and what moved since the last recorded run
-e
Short for --explain
--explain
For a ref with charms: show the per-charm argv trace (base then each charm)
--inputs
With --cache: list every key input line, so you can confirm a declared file was actually hashed
--no-default-charms
With --cache: ignore magus.yaml default_charms when keying, matching a run made the same way (CI)

describe projects options

-e
Short for --evaluated
--evaluated
Print workspace-rooted globs, effective claims, and per-target policies

describe spells options

--versions
Probe each spell's tools and report the versions that would key a run

Subcommands

targets
List every target the workspace defines
target
Detail one target ref: its dispatch plan, globs, spells and policy
projects
List the workspace's projects
project
Detail one named project; takes the same flags as projects
spells
List the spells the workspace resolves
charms
List charms and the targets that declare them
workspaces
List the workspaces registered in config
modules
List the Buzz host modules a magusfile can import
mcp-tools
List the tools the MCP server exposes
tools
List the external tools the workspace's spells require
file
Classify paths as generated output, declared source, maintained, or unclaimed
graph
Emit the target catalog and dependency graph

Examples

List every target

magus describe targets

List a charm's declaring targets

magus describe charm rw

Detail one project

magus describe project api

Preview a charm-applied command

magus describe target lint:rw

Trace how each charm reshapes the command

magus describe target --explain lint:rw,debug

See Also

magus(1), magus-ls(1), magus-run(1), magus-x(1), magus-where(1), magus-affected(1), magus-graph(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. magus DocumentationThe magus documentation hub covering install, targets, spells, charms, operations, engines, remote caching, MCP, telemetry, and the interactive playground. magus-queryQuery the magus knowledge graph to find and relate entities (projects, targets, spells, ops, charms, modules, diagnostics, docs).
generatedinternal/cli/registry.goclimagus describespellcharmtargetprojectworkspacemodulemcp-tooltoolfilegraphintrospection
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.

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. See targets.

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.

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.

Trace

OpenTelemetry's name for one whole magus invocation; every target it runs is a span beneath it. See telemetry.

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.