Use -h for a summary or --help for all flags:

musubi --help
musubi <command> --help

Running musubi with no command is musubi list. How jj-musubi works explains hubs, hives, and copies.

Share repos

CommandUse it to
create [<name>]Start a hive from the repo you’re in, for other copies to join.
joinJoin this copy to its matching hive, or recreate a lost hive on this hub or another named by --hub. A filesystem duplicate can take over the original’s identity with --original once that copy is gone.
clone <hive> [<dir>]Create a copy in a new or empty <dir>, making missing parents, and check out trunk() using local jj config. Without <dir>, use the hive name’s last component (dotfiles for bos/dotfiles) in the current directory, even with an abbreviated hive name. The hive’s creation defaults fill missing settings (name and email by default); existing settings win. Git remotes aren’t copied. Objects use the hive’s SHA-1 or SHA-256 hash, regardless of git.object-hash.
leaveAttempt a final sync, then leave the hive, keeping the repo and files. --force still attempts this sync but leaves even if it fails. leave <path> stops looking for a copy that is gone. See Pause syncing or leave.
forget <machine>Forget another machine’s missing copy, or an old deleted copy here, even without workspaces. musubi status lists copies. Use the machine part of its workspace name: laptop for laptop/default@, laptop-1a2b for laptop-1a2b/default@, or its full id if prefixes collide (laptop-1a2b3c4d/default@). The name from musubi list also works if unambiguous.

create, join, and clone take:

  • --hub <hub>: the hub, as musubi hub prints it. On the hub’s machine, its name or localhost means the hub musubi hub serves there without --dir, reached without ssh. Without it, they use this machine’s default hub: the first it used, unless musubi.hub names another.
  • --machine <name>: this machine’s name in the hive, which other machines show its working copies under. It defaults to jj’s operation.hostname.
  • --lease <duration>: forget this copy after that long without a local operation, such as --lease 6h. Sets musubi.forget-after in this copy’s repo config.

create and join also take --full-history, to share the repo’s whole operation history rather than its current state, and join takes --hive <name> to join a hive of your choosing. Without --lease, all three keep the copy’s configured musubi.forget-after, or set never when none is configured. Agent-run commands have the same default. See Set up a hub and machines.

See how syncing goes

CommandUse it to
listShow hubs’ hives, local copies and sync state. -T uses a template; see musubi list --help. Use -T 'json(self) ++ "\n"' for JSON.
statusReport this copy’s hive, hub, workspaces, last sync, pending work, other copies’ activity and expiry, and daemon state. Warn of problems with recovery hints. Outside a hive, show the default hub and daemon. -T uses a template (musubi status --help); -T 'json(self) ++ "\n"' produces JSON.
syncSync this copy now. --outgoing inspects snapshot overhead without sending. --approve TOKEN approves the inspected history. --prune OPERATION... snapshots current edits and deletions, then discards unpublished operations while preserving current work and explicit change versions. Add --dry-run to preview recorded history without snapshotting or changing it. See snapshot cleanup. For an ambiguous operation abandon, first restore missing history with the jj op integrate hint.
topWatch hub traffic and machines that are offline, behind, or failing.

status reads local state without starting the daemon or contacting the hub. It always exits 0; warnings and hints go to standard error.

Sending pauses above 1,000 extra file paths or 64 MiB in outgoing snapshots, beyond explicit change history and shared content; receiving continues. musubi sync --outgoing lists extra paths without snapshotting or contacting the hub. Within publication budget means the work fits, not that it was sent. See Snapshot limits and cleanup for the workflow and configuration for setting semantics.

musubi status as JSON

musubi status -T 'json(self) ++ "\n"' prints one JSON object. Times are seconds since the Unix epoch; durations are seconds. Unknown or inapplicable values are null, where -T keywords give an empty string or false. The keyword problem maps to not_synced, else hive.error; status comes from hive.last_sync, except during a snapshot hold, when it is sending held: snapshot publication budget; daemon_running is daemon.running.

FieldValue
repositoryThe workspace containing the current directory. null outside a jj repo or if unavailable; not_synced explains unavailable state.
hiveThe repo’s part in its hive, or null outside one: name, id, hub, machine (this machine’s name in the hive), head (the hive’s head, as of the last sync), last_sync, error (why its syncing fails), sent (whether the hub has all this machine’s work, as far as the last sync tells), forgotten, working_copies (each with name, commit, change and description), and copies (each with machine, this, last_used, and forget_after, null for never).
not_syncedWhy a recorded copy does not sync (such as a filesystem duplicate), or why its state is unavailable (such as a missing directory or repo). hive is null in these cases; otherwise not_synced is null. See Move, copy or restore a repo.
default_hubThe hub commands use without --hub, or null.
daemonrunning (null if unknown), error (why its state is unknown or a running daemon is unreachable), pid, serving (whether it serves this repo), served (repo count), at_login, socket, log, and upgrade_failed (release and error if its last upgrade to a release newer than this command failed, otherwise null).

For unattended checks, read daemon.running, daemon.serving, hive.error, hive.last_sync and hive.sent on each machine, allowing for expected offline periods. An old successful sync isn’t evidence of current health; a sender’s hive.sent does not show that every receiver has caught up. Neither status nor top --once signals reported problems with a failing exit status. See Monitor syncing for the workflow.

Read musubi top

musubi top asks the known hubs for their reports and refreshes every five seconds.

musubi top: 1 hub, every 5s
This machine's daemon is running, serving 2 repositories.
Hub devbox: up 3h12m, musubi 0.1.0, 2 hives.
Issues:
  app: gpu not heard from in 6m: offline, or its daemon isn't running

HIVE      HEAD  IN/s     OUT/s    OPS  COMMITS  MACHINES  ISSUES
app       #412  12 KiB/s 40 KiB/s 96   51       2/3       1
dotfiles  #88   0 B/s    0 B/s    3    1        1/1

app since the hub started:
  received 4.1 MiB and sent 12 MiB
  96 operations came in, with 51 commits, and 180 went out
  40 pushes moved the head, and 2 found it moved already
  MACHINE  HEARD   AT    MUSUBI  STATE
  devbox   3s ago  #412  0.1.0   up to date
  gpu      6m ago  #401  0.1.0   not heard from in 6m: offline, or its daemon isn't running
  laptop   2s ago  #412  0.1.0   up to date

  AGO     HEAD  FROM    OPS  COMMITS  WHAT
  2s ago  #412  laptop  1    1        snapshot working copy

The hive rows show transfer rates and incoming operations and commits since hub startup. Pick a hive with the arrow keys to see its machines and latest updates, named as jj op log names them.

FieldMeaning
HEADThe hub’s current update number.
ATA machine’s last reported update; compare with HEAD to see if it caught up.
IN/s, OUT/sBytes per second received and sent by the hub.
OPS, COMMITSIncoming operations and commits since the hub started.
MACHINESUp-to-date reports over listed machines: 2/3 means two of three are up to date.
ISSUESProblems reported for the hive.
STATEThe machine’s reported sync state. A sleeping machine may be quiet without failing.

Issues list unreachable hubs, failed requests and machines offline, behind or failing to sync. An offline machine appears in the issues list when first found quiet; its row stays red and ISSUES still counts it. It appears again if heard from and then quiet again. See troubleshooting for recovery.

q quits; space, Enter or t refreshes; d, s or i sets the refresh interval; Ctrl-L redraws. + and - refresh less or more often. Without a terminal, or with --once, it prints one snapshot without rates. top sends no unattended alerts; --once exits successfully even with issues.

Reports live in hub memory. After a restart, machines reappear at their next sync, within half a minute. Reports expire after a day without contact.

Run the daemon

CommandUse it to
daemon installStart the daemon now and at login.
daemon uninstallStop the daemon and remove login startup.
daemon startStart the daemon in the background, unless it is running.
daemon stopStop background syncing for copies served by this daemon, keeping memberships and login startup. The hub keeps running; explicit sync still works.
daemon restartStop the daemon and start it again, as after upgrading jj-musubi.
daemonRun the daemon in the foreground, logging to the terminal.

create, join, and clone start a missing daemon and wait for the first sync. sync uses the daemon if running, or syncs directly with a warning. Each shows progress on a terminal.

Run a hub

CommandUse it to
hubRun a hub, in the foreground. --dir chooses its directory, and --advertise the host name it tells other machines to use.
hub installStart the hub now and at login, or at boot with --at-boot, as your user. Boot installation uses sudo; run the command without sudo. Accepts the same flags as hub. macOS and Linux only.
hub uninstallStop the hub and remove its login or boot service. Removing a boot service uses sudo.
hub rename <hive> <new-name>Rename a hive.
hub remove <hive>Remove a hive from the hub. Each machine’s copy leaves it as it hears. rm is an alias.
hub connectRelay standard input and output to this machine’s hub. Other machines use it over ssh.

Hives can be named by an unambiguous prefix or id. hub remove requires a whole name or id.

musubi hub prints commands, including when local commands can omit --hub. It recognizes symlinks to the default hub directory. If its saved path is too long, use the shorter --hub path it prints.

Complete commands in your shell

Add the line for your shell to complete commands, flags, paths, hives and hubs as you type. Start a new shell after upgrading: the completion interface can change.

ShellStartup fileLine
bash~/.bashrcsource <(COMPLETE=bash musubi)
zsh~/.zshrc, after compinitsource <(COMPLETE=zsh musubi)
fish~/.config/fish/config.fishCOMPLETE=fish musubi | source
elvish~/.config/elvish/rc.elveval (E:COMPLETE=elvish musubi | slurp)
PowerShell$PROFILE$env:COMPLETE = "powershell"; musubi | Out-String | Invoke-Expression; Remove-Item Env:\COMPLETE

Hive completion waits up to two seconds for the default hub, then falls back to hives with copies on this machine using that hub.

musubi completion <shell> prints a static script for commands, flags and paths, without hive or hub names. Use it for nushell or packaged completion files. It accepts bash, elvish, fish, nushell, powershell or zsh:

source <(musubi completion zsh)

Investigate

musubi debug investigates hives; it is omitted from musubi --help.

Operations include each machine’s Git refs and workspaces, so their ids differ between copies and the hub. Commands such as jj op restore <id> take the local id. Run musubi debug op-id <id> here to get its hive id, then run musubi debug op-id with that id in the other machine’s repo to find its local counterpart.

CommandUse it to
debug op-id <id>Translate an operation id between this machine’s id and the hive’s.

Global options

OptionEffect
--color <when>Choose when to colour what the command prints: always, never, debug (showing labels), or auto (only on a terminal). Without it, jj’s ui.color says. See Colours.
--log <filter>Choose what this command logs, as a filter in RUST_LOG’s syntax, such as debug or musubi_sync=debug. See Logging.
--socket <path>Talk to the daemon on another control socket: an absolute path, or one starting with ~/. See Files and directories.

If a reader closes stdout early, as in musubi list | head, the command finishes its work, stops printing and exits 3, as jj does.