Skip to main content

Commands

mani​

repositories manager and task runner

Options​

      --color                enable color (default true)
  -c, --config string        specify config
  -h, --help                 help for mani
  -u, --user-config string   specify user config

run​

Run tasks

Synopsis​

Run tasks.

The tasks are specified in a mani.yaml file along with the projects you can target.

run <task>

Examples​

  # Execute task for all projects
  mani run <task> --all

  # Execute a task in parallel with a maximum of 8 concurrent processes
  mani run <task> --projects <project> --parallel --forks 8

  # Execute task for a specific projects
  mani run <task> --projects <project>

  # Execute a task for projects with specific tags
  mani run <task> --tags <tag>

  # Execute a task for projects matching specific paths
  mani run <task> --paths <path>

  # Execute a task for all projects matching a tag expression
  mani run <task> --tags-expr 'active || git' <tag>

  # Execute a task with environment variables from shell
  mani run <task> key=value

Options​

  -a, --all                   select all projects
  -k, --cwd                   select current working directory
      --describe              display task information
      --dry-run               display the task without execution
  -e, --edit                  edit task
  -f, --forks uint32          maximum number of concurrent processes (default 4)
  -h, --help                  help for run
      --ignore-errors         continue execution despite errors
      --ignore-non-existing   skip non-existing projects
      --omit-empty-columns    hide empty columns in table output
      --omit-empty-rows       hide empty rows in table output
  -o, --output string         set output format [stream|table|markdown|html]
      --parallel              execute tasks in parallel across projects
  -d, --paths strings         select projects by path
  -p, --projects strings      select projects by name
  -s, --silent                hide progress output during task execution
  -J, --spec string           set spec
  -t, --tags strings          select projects by tag
  -E, --tags-expr string      select projects by tags expression
  -T, --target string         select projects by target name
      --theme string          set theme
      --tty                   replace current process

exec​

Execute arbitrary commands

Synopsis​

Execute arbitrary commands. Use single quotes around your command to prevent file globbing and environment variable expansion from occurring before the command is executed in each directory.

exec <command> [flags]

Examples​

  # List files in all projects
  mani exec --all ls

  # List git files with markdown suffix in all projects
  mani exec --all 'git ls-files | grep -e ".md"'

Options​

  -a, --all                   target all projects
  -k, --cwd                   use current working directory
      --dry-run               print commands without executing them
  -f, --forks uint32          maximum number of concurrent processes (default 4)
  -h, --help                  help for exec
      --ignore-errors         ignore errors
      --ignore-non-existing   ignore non-existing projects
      --omit-empty-columns    omit empty columns in table output
      --omit-empty-rows       omit empty rows in table output
  -o, --output string         set output format [stream|table|markdown|html]
      --parallel              run tasks in parallel across projects
  -d, --paths strings         select projects by path
  -p, --projects strings      select projects by name
  -s, --silent                hide progress when running tasks
  -J, --spec string           set spec
  -t, --tags strings          select projects by tag
  -E, --tags-expr string      select projects by tags expression
  -T, --target string         target projects by target name
      --theme string          set theme
      --tty                   replace current process

init​

Initialize a mani repository

Synopsis​

Initialize a mani repository.

Creates a new mani repository by generating a mani.yaml configuration file and a .gitignore file in the current directory.

With --source <provider>/<name>, mani fetches repositories from a remote source and scaffolds mani.yaml from them. The query is persisted in a 'sources:' block so 'mani refresh' can pick up new repos later.

Supported providers:

  • github/<name> auto-detect org or user (requires 'gh')
  • github-org/<name> explicit organization (requires 'gh')
  • github-user/<name> explicit user (requires 'gh')
  • gitea/<name>, forgejo/<name>, codeberg/<name> auto-detect (all Gitea-compatible) (requires 'tea')
  • gitea-org/<name>, forgejo-org/<name>, codeberg-org/<name> (requires 'tea')
  • gitea-user/<name>, forgejo-user/<name>, codeberg-user/<name> (requires 'tea')

The provider's CLI must be installed and authenticated before use. The auto-detect form (github/, gitea/, …) probes the org endpoint first and falls back to the user endpoint; explicit -org/-user forms skip the probe and go directly to the right endpoint.

init [flags]

Examples​

  # Initialize with default settings (local auto-discovery)
  mani init

  # Initialize from a GitHub organization
  mani init --source github/my-org

  # Initialize from a Codeberg user
  mani init --source codeberg/some-user

  # Initialize from a GitHub org, placing all repos under a common path
  mani init --source github/my-org --source-path my-org

  # Initialize from a Gitea org, including archived repos and forks
  mani init --source gitea/my-org --archived

  # Initialize from a GitHub org with a smaller limit and no topic tags
  mani init --source github/my-org --limit 50 --no-topic-tags

  # Initialize without auto-discovering projects
  mani init --auto-discovery=false

  # Initialize without updating .gitignore
  mani init --sync-gitignore=false

Options​

      --archived             include archived repositories (default: exclude)
      --auto-discovery       automatically discover and add Git repositories to mani.yaml (default true)
      --fork                 include forked repositories (default true)
  -h, --help                 help for init
      --limit int            maximum number of repositories to fetch from the remote source (default 1000)
      --no-tags              omit synthesized tags from generated projects
      --no-topic-tags        omit topic=<name> tags
      --source string        remote source to scaffold projects from (e.g. github/my-org, gitea/foo, codeberg/joe)
      --source-path string   common path prefix under which the source's projects are placed
  -g, --sync-gitignore       synchronize .gitignore file (default true)

refresh​

Update mani.yaml with new projects from remote sources and local clones

Synopsis​

Update the 'projects:' mapping in mani.yaml from two places:

  1. Remote sources — re-query each entry in the 'sources:' block and append any new upstream repositories.
  2. Local clones — unless --auto-discovery=false, walk the config directory for git repositories that aren't listed yet and append them (the same discovery 'mani init' performs). This is how a repo you 'git clone' into the workspace by hand gets picked up.

By default, refresh only adds projects. Existing entries are left untouched — any local edits (renames, custom tags, env, etc.) are preserved. Projects whose upstream repository is gone are reported as stale; use --prune to also remove them. Pruning is scoped to each source's remote, so projects from a different remote (or discovered locally) are never removed.

The 'sources:' block is optional: a config from a plain 'mani init' has none, and refresh still picks up local clones. Sources do require the provider CLI to be installed and authenticated:

  • github sources need 'gh'
  • gitea/forgejo/codeberg sources need 'tea'
refresh [flags]

Examples​

  # Append new upstream repos and locally-cloned repos to projects:
  mani refresh

  # Show what would change without writing
  mani refresh --dry-run

  # Only re-query remote sources, skip local discovery
  mani refresh --auto-discovery=false

  # Also delete projects whose upstream repo is gone
  mani refresh --prune

Options​

      --auto-discovery   discover locally-cloned git repositories and add them to mani.yaml (default true)
      --dry-run          show what would change but do not modify mani.yaml
  -h, --help             help for refresh
      --prune            remove projects whose upstream repository no longer exists

sync​

Clone repositories and update .gitignore

Synopsis​

Clone repositories and update .gitignore file. For repositories requiring authentication, disable parallel cloning to enter credentials for each repository individually.

sync [flags]

Examples​

  # Clone repositories one at a time
  mani sync

  # Clone repositories in parallel
  mani sync --parallel

  # Disable updating .gitignore file
  mani sync --sync-gitignore=false

  # Sync project remotes. This will modify the projects .git state
  mani sync --sync-remotes

  # Clone repositories even if project sync field is set to false
  mani sync --ignore-sync-state

  # Display sync status
  mani sync --status

Options​

  -f, --forks uint32                maximum number of concurrent processes (default 4)
  -h, --help                        help for sync
      --ignore-sync-state           sync project even if the project's sync field is set to false
  -p, --parallel                    clone projects in parallel
  -d, --paths strings               clone projects by path
  -w, --remove-orphaned-worktrees   remove git worktrees not in config
  -s, --status                      display status only
  -g, --sync-gitignore              sync gitignore (default true)
  -r, --sync-remotes                update git remote state
  -t, --tags strings                clone projects by tags
  -E, --tags-expr string            clone projects by tag expression

edit​

Open up mani config file

Synopsis​

Open up mani config file in $EDITOR.

edit [flags]

Examples​

  # Edit current context
  mani edit

Options​

  -h, --help   help for edit

edit project​

Edit mani project

Synopsis​

Edit mani project in $EDITOR.

edit project [project] [flags]

Examples​

  # Edit projects
  mani edit project

  # Edit project <project>
  mani edit project <project>

Options​

  -h, --help   help for project

edit task​

Edit mani task

Synopsis​

Edit mani task in $EDITOR.

edit task [task] [flags]

Examples​

  # Edit tasks
  mani edit task

  # Edit task <task>
  mani edit task <task>

Options​

  -h, --help   help for task

project​

Add or remove projects in mani.yaml

Synopsis​

Add or remove projects in mani.yaml.

Edits are lossless: comments, blank lines, indentation, and any hand-customized fields outside the touched entry are preserved byte-for-byte. The edited file is validated as YAML before it is written, so a failed edit never corrupts the config.

Examples​

  # Add a remote project (cloned on next sync)
  mani project add my-repo --url git@github.com:org/my-repo.git --tags backend

  # Remove a project
  mani project rm my-repo

Options​

  -h, --help   help for project

project add​

Add a project to mani.yaml

Synopsis​

Add a project to mani.yaml.

A repository URL is required — either as the argument or via --url:

  • A git URL (https://…, ssh://…, git@host:org/repo.git) is recorded as the project's url and the project name is derived from the repo (the final path segment, minus ".git"). Override the derived name with --name.
  • A plain name needs --url to supply the repository.

The project is appended to the 'projects:' mapping and cloned on the next 'mani sync'. Comments and formatting elsewhere in mani.yaml are preserved.

project add <name|url> [flags]

Examples​

  # Add from a URL — name is derived (-> "mani")
  mani project add https://github.com/alajmo/mani.git

  # Add from a URL but choose the name
  mani project add https://github.com/alajmo/mani.git --name kaka

  # Add by name with an explicit url and tags
  mani project add my-repo --url git@github.com:org/my-repo.git --tags backend

  # Add a remote, cloned to a custom path with a description
  mani project add my-lib --url git@github.com:org/my-lib.git --path ./libs/my-lib --desc "shared lib"

Options​

      --desc string   project description
  -h, --help          help for add
      --name string   project name (defaults to the repo name derived from a URL argument)
      --path string   local directory path relative to mani.yaml (defaults to the project name)
      --tags string   comma-separated tags
      --url string    git repository URL (cloned on next sync)

project remove​

Remove a project from mani.yaml

Synopsis​

Remove a project from mani.yaml.

The project entry, together with the comment and blank lines directly above it, is removed; all other formatting is preserved. The project's files on disk are NOT deleted. You are prompted for confirmation unless --force is given.

project remove <name> [flags]

Examples​

  # Remove a project (prompts for confirmation)
  mani project rm my-repo

  # Remove without prompting
  mani project rm my-repo --force

Options​

  -f, --force   skip the confirmation prompt
  -h, --help    help for remove

list projects​

List projects

Synopsis​

List projects.

list projects [projects] [flags]

Examples​

  # List all projects
  mani list projects

  # List projects by name
  mani list projects <project>

  # List projects by tags
  mani list projects --tags <tag>

  # List projects by paths
  mani list projects --paths <path>

	# List projects matching a tag expression
	mani run <task> --tags-expr '<tag-1> || <tag-2>'

Options​

  -a, --all                select all projects (default true)
  -k, --cwd                select current working directory
      --headers strings    specify columns to display [project, path, relpath, description, url, tag, worktree] (default [project,tag,description])
  -h, --help               help for projects
  -d, --paths strings      select projects by paths
  -t, --tags strings       select projects by tags
  -E, --tags-expr string   select projects by tags expression
  -T, --target string      select projects by target name
      --tree               display output in tree format

Options inherited from parent commands​

  -o, --output string   set output format [table|markdown|html] (default "table")
      --theme string    set theme (default "default")

list tags​

List tags

Synopsis​

List tags.

list tags [tags] [flags]

Examples​

  # List all tags
  mani list tags

Options​

      --headers strings   specify columns to display [project, tag] (default [tag,project])
  -h, --help              help for tags

Options inherited from parent commands​

  -o, --output string   set output format [table|markdown|html] (default "table")
      --theme string    set theme (default "default")

list tasks​

List tasks

Synopsis​

List tasks.

list tasks [tasks] [flags]

Examples​

  # List all tasks
  mani list tasks

  # List tasks by name
  mani list task <task>

Options​

      --headers strings   specify columns to display [task, description, target, spec] (default [task,description])
  -h, --help              help for tasks

Options inherited from parent commands​

  -o, --output string   set output format [table|markdown|html] (default "table")
      --theme string    set theme (default "default")

describe projects​

Describe projects

Synopsis​

Describe projects.

describe projects [projects] [flags]

Examples​

  # Describe all projects
  mani describe projects

  # Describe projects by name
  mani describe projects <project>

  # Describe projects by tags
  mani describe projects --tags <tag>

  # Describe projects by paths
  mani describe projects --paths <path>

	# Describe projects matching a tag expression
	mani run <task> --tags-expr '<tag-1> || <tag-2>'

Options​

  -a, --all                select all projects (default true)
  -k, --cwd                select current working directory
  -e, --edit               edit project
  -h, --help               help for projects
  -d, --paths strings      filter projects by paths
  -t, --tags strings       filter projects by tags
  -E, --tags-expr string   target projects by tags expression
  -T, --target string      target projects by target name

Options inherited from parent commands​

      --theme string   set theme (default "default")

describe tasks​

Describe tasks

Synopsis​

Describe tasks.

describe tasks [tasks] [flags]

Examples​

  # Describe all tasks
  mani describe tasks

  # Describe task <task>
  mani describe task <task>

Options​

  -e, --edit   edit task
  -h, --help   help for tasks

Options inherited from parent commands​

      --theme string   set theme (default "default")

tui​

TUI

Synopsis​

Run TUI

tui [flags]

Examples​

  # Open tui
  mani tui

Options​

  -h, --help               help for tui
  -r, --reload-on-change   reload mani on config change
      --theme string       set theme (default "default")

check​

Validate config

Synopsis​

Validate config.

check [flags]

Examples​

  # Validate config
  mani check

Options​

  -h, --help   help for check

gen​

Generate man page

gen

Options​

  -d, --dir string   directory to save manpage to (default "./")
  -h, --help         help for gen