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

magus-events

Stream workspace events as JSONL for an integration to consume

Synopsis

magus events [flags]

Description

Stream workspace events as JSONL, one event per line. This is the surface third-party integrations build against: an Emacs or Vim plugin, a status bar, a notifier.

Every magus process in the workspace feeds the stream, so a run started in another terminal shows up here. It needs no daemon, no token, and no loadable magusfile - an editor can attach to a repository whose magusfile is mid-edit.

The stream is outbound only. Nothing a subscriber does can change a magus verdict; the inbound counterpart is the session hook.

target.output is excluded unless named with --type: it is the one event type that scales with build size rather than project count. To read a target's full log, take the ref from its target.result event and pass it to query output.

A subscriber must ignore event types and fields it does not recognize. That is what lets the taxonomy grow without breaking clients built against an earlier schema.

Options

-f
Short for --follow
--follow
Keep streaming as events occur instead of exiting after the replay
--interval duration (default: 250ms)
How often --follow polls the run log for new events
--limit int (default: 20)
Replay this many recent invocations before following; 0 replays nothing (only new events), negative replays every retained run
--type string
Restrict to these event types (comma-separated); default is every type except target.output

Examples

Watch a workspace live

magus events --follow

Only what an editor needs for progress

magus events --follow --type run.started,target.result

What did the last run do

magus events --limit 1

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-query(1), magus-explain(1), magus-path(1), magus-refs(1), magus-watch(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. magus affectedRun a target for every project affected by a VCS diff, with forensic modes for explain, graph, CI shard plan, and regression bisect. magus runRun a named target (build, test, lint, format, ci, etc.) for the selected projects, defaulting to the cwd project when no arguments are given. magus-queryQuery the magus knowledge graph to find and relate entities (projects, targets, spells, ops, charms, modules, diagnostics, docs).
generatedinternal/cli/registry.goclimagus eventseventsintegrationeditorpluginjsonlsubscribe
Last updated (4f8cc295)
Earlier changes on this page (1)

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.

Buzz

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

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.

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.