Commands

Every capability is a command, so a person, a script, or an agent can reach any outcome.

This page explains when and why to reach for each command. For an exhaustive list of every command and flag, see the command reference, which is generated from the binary and so never drifts.

Shared options

Every command accepts these.

Option	Does
`--json`	Emit JSON instead of a table, for scripts and agents.
`--refresh`	Ignore cached data and ask the provider again.
`--owner <OWNER>`	Keep only repositories owned by these accounts. Repeatable.
`--group <GROUP>`	Keep only repositories in these groups, which are the directories beneath a root. Repeatable.
`--state <STATE>`	Keep only repositories in these states. Repeatable.
`--include-forks`	Include forks, which are hidden by default.
`--include-external`	Include clones of repositories owned by nobody you track, which are hidden by default.

Filters combine rather than accumulate: naming an owner and a state requires both. All of them are matched without regard to case.

--owner applies everywhere, including list and sync-fork. --group and --state describe a local clone, so they apply to the commands that read one, status, tui, and the actions, and have no effect on list or sync-fork, which work from what the provider reports.

--json describes a report, so it has no effect on tui, which is a terminal to sit in, or on completions, whose output is a shell script and stops being one if it is wrapped.

Forks and external clones are left out by default, so the usual view is the repositories you maintain. A fork is any repository the provider reports as one. An external clone is one whose remote owner is not a configured account. Add --include-forks or --include-external to bring either back.

States

Value	Means
`not-cloned`	Reported by the provider, with no local clone, so it is not backed up locally.
`in-sync`	Matching the remote exactly.
`ahead`	Holding commits the remote does not.
`behind`	Missing commits the remote has.
`diverged`	Both sides hold commits the other lacks.
`local-only`	A clone no reported repository corresponds to, so it is the only copy.
`incomparable`	A clone that cannot be compared, such as one with no commits or a detached head.
`drifted`	Anything that is not in sync, which is usually what wants attention.

Only working clones are compared. A bare repository or mirror has no working tree, so status reports it and moves on rather than treating it as a clone. A symlinked directory is not followed, and is reported the same way, so a projects tree kept behind a symlink is not silently missing.

Reading

`minato list`

Every repository the provider reports, with stars, issues, pull requests, licence, language, and when it was last pushed.

Terminal

minato list --owner mcanouil

`minato status`

How local clones stand against what the provider reports.

Terminal

minato status --group demo
minato status --state behind --state diverged

Output

PATH                                    REPOSITORY                    GROUP  STATE     NOTES
/Users/you/Projects/forks/pandoc        github:mcanouil/pandoc        forks  in sync   fork, 429 behind upstream
/Users/you/Projects/perso/imdb-ratings  github:mcanouil/imdb-ratings  perso  behind 2

`minato doctor`

Checks git, the token, configuration, roots, the cache, and whether any installed shell completion script has fallen behind the command surface, reporting all of them rather than stopping at the first problem.

`minato auth status`

Whether a token was found and where it came from, never the token itself.

`minato refresh`

Discards cached data so the next run asks the provider again.

`minato completions`

Prints a shell completion script for bash, zsh, fish, powershell, or elvish, or installs one.

Terminal

minato completions --install          # the shell from $SHELL, written where it reads it
minato completions zsh --dry-run --install
minato completions zsh --uninstall
minato completions zsh > ~/.zfunc/_minato

The script is generated from the command definitions, so it offers exactly the commands and flags the binary has, and a new one is completed without anything being regenerated by hand. Printing is the default, so a redirect or a pipe still works. --install picks the destination for you and edits your shell’s configuration only where the file alone is not enough. A script already on disk is updated where it is rather than moved, and copies left in other known places are swept. See Shells for every destination and for doing it by hand.

Flag values that are a fixed set complete too, so --state offers its eight values, in bash, zsh, and fish. The powershell and elvish scripts complete commands and flag names only, because those generators do not carry a flag’s values.

Changing things

Each of these takes --dry-run, which reports what happens and changes nothing. One repository failing never stops the others: every repository is reported, and the process exits non-zero if any failed.

`minato clone`

Clones repositories that have no local copy.

Option	Does
`--into <DIRECTORY>`	Where to put them. Defaults to the first configured root.
`--into-group <GROUP>`	Put them in the directory that group already occupies.
`--shallow`	Clone with a truncated history.

Terminal

minato clone --state not-cloned --into-group demo --dry-run

Note

--into-group is not the --group filter. The filter selects by where a clone already sits, and a repository that has not been cloned is in no group, so filtering clone by one matches nothing.

Anything already at the destination is skipped rather than written over.

`minato fetch`

Fetches every clone, updating remote-tracking refs only. It never touches a working tree, so it is safe to run at any time, including on a repository with uncommitted changes.

Terminal

minato fetch --group quarto-dev

`minato update`

Fast-forwards clones that are strictly behind and have no modified tracked files.

Terminal

minato update --dry-run
minato update

Everything else is reported with the reason it was left alone, because a repository that cannot be updated is exactly the one worth knowing about.

Untracked files do not block an update: git fast-forwards alongside them, and refuses by itself in the one case where it overwrites one.

`minato sync-fork`

Syncs forks with their upstream through GitHub’s merge-upstream, fast-forward only.

Terminal

minato sync-fork --dry-run
minato sync-fork

Only a fork strictly behind its upstream is synced. A fork holding its own commits has diverged, so it is reported and left alone rather than merged, and no history is ever rewritten. Nothing is cloned or pushed: the sync happens on GitHub.

`minato move`

Moves one repository into another group, which means moving its directory.

Terminal

minato move imdb-ratings --to-group demo --dry-run

Deliberately one repository at a time, and never a side effect of another command. It refuses rather than guesses: an ambiguous name lists the matches, an occupied destination is left untouched, and a repository already in that group is not moved onto itself.

The directory keeps its own name, which is not always the repository name.

Browsing

`minato tui`

Opens a keyboard-driven table over exactly the comparison the commands produce.

Key	Does
`j` `k`, arrows	Move. `g` and `G` jump to the ends.
`/`	Search by repository, group, or path.
`s`	Cycle the ordering: name, state, group.
`f` `u`	Fetch or update the highlighted repository.
`r`	Rescan the disk.
`q`	Leave.

Sorting by state puts what needs attention first. Reloading rescans the disk but does not refetch, since a keystroke must not spend your rate limit.

It needs a terminal, and says so plainly when there is not one rather than failing obscurely.