Modules

An overview of the packages that make up mibare. The API reference below is generated automatically from the source docstrings.

Core (mibare.core)

Always-included infrastructure.

Resolve a repository to a ranked list of mise backend candidates.

mibare.core.resolve.SCHEMA_VERSION = 1

Version of the shape Resolution.to_dict returns; bumped on breaking changes.

class mibare.core.resolve.Candidate(backend_string, reasons=(), tier=5, legacy=False, warning=None, registry_name=None, windows_target=False)

Bases: object

A backend string that could install the tool for a repository.

Parameters:

• backend_string (str)

• reasons (tuple[str, ...])

• tier (int)

• legacy (bool)

• warning (str | None)

• registry_name (str | None)

• windows_target (bool)

backend_string

The backend and tool identifier, as in aqua:owner/repo.

Type:

str

reasons

Short explanations of why it is a candidate; each resolution step that finds the backend string appends its own.

Type:

tuple[str, …]

tier

Position on mise’s preference ladder, 1 (packslip) to 5 (plugins); lower is better. Defaults to the lowest tier.

Type:

int

legacy

Whether the backend is a legacy backend (asdf, vfox, ubi).

Type:

bool

warning

Why the candidate is discouraged, or None.

Type:

str | None

registry_name

The registry short name to install it by, set only for the backend mise itself picks first for that name, so the entry’s options apply; None otherwise.

Type:

str | None

windows_target

Whether the target platform is Windows, so the command is quoted for cmd.exe instead of a POSIX shell.

Type:

bool

property mise_use: str

A ready-to-paste mise use command for this candidate.

It names the registry short name when registry_name is set and the backend string otherwise. The argument is quoted for the target platform’s shell, since the command is pasted where the tool will be installed: double quotes for a Windows target, POSIX quotes otherwise.

class mibare.core.resolve.Exclusion(backend_string, reason)

Bases: object

A backend string that was considered and left out.

Parameters:

• backend_string (str)

• reason (str)

backend_string

The backend string that was excluded.

Type:

str

reason

Why it was excluded.

Type:

str

class mibare.core.resolve.Resolution(repository, mise_version, candidates, exclusions=(), platform=None, notes=())

Bases: object

The outcome of resolving a repository.

Parameters:

• repository (Repository)

• mise_version (str)

• candidates (tuple[Candidate, ...])

• exclusions (tuple[Exclusion, ...])

• platform (Platform | None)

• notes (tuple[str, ...])

repository

The repository that was resolved.

Type:

mibare.core.repository.Repository

mise_version

The mise version whose registry the answer came from.

Type:

str

candidates

The candidates, best first.

Type:

tuple[mibare.core.resolve.Candidate, …]

exclusions

The backend strings considered and left out, each with the reason.

Type:

tuple[mibare.core.resolve.Exclusion, …]

platform

The target platform the candidates are for.

Type:

mibare.core.platform.Platform | None

notes

Remarks for the user, such as a target that differs from the host.

Type:

tuple[str, …]

property recommendation: Candidate | None

The top-ranked candidate, or None when there is no backend.

to_dict()

Return the documented, stable JSON shape of this resolution.

The keys, in order: schema_version (int), repository (owner/repo), mise_version, recommendation (the first candidate’s backend string, or null), candidates (best first, each with backend_string, recommended, tier (int), legacy (bool), warning (text or null), command and reasons), excluded (each with backend_string and reason), platform (os-arch or null) and notes (a list of text).

command is always a string. It names the registry short name for the backend mise itself picks first for a registry entry (so the entry’s options, which mise registry --json omits, apply), and the explicit backend string for every other candidate; backend_string stays the candidate’s identity either way. An argument that needs quoting is quoted for the target platform’s shell: double quotes for a Windows target, POSIX single quotes otherwise.

Returns:

A structure that json.dumps accepts.

Return type:

dict[str, object]

mibare.core.resolve.resolve(repository, mise, platform=None, github=None, ecosystems=(Ecosystem(backend='pypi', languages=frozenset({'Python'}), detect=<function _detect_python>), Ecosystem(backend='cargo', languages=frozenset({'Rust'}), detect=<function _detect_cargo>), Ecosystem(backend='npm', languages=frozenset({'JavaScript', 'TypeScript'}), detect=<function _detect_npm>), Ecosystem(backend='go', languages=frozenset({'Go'}), detect=<function detect_go>)))

Resolve repository to the mise backends that can install it.

Parameters:

• repository – A GitHub URL or owner/repo shorthand.

• mise – The mise adapter.

• platform – The target platform; defaults to the host.

• github – The GitHub adapter. Without one the steps that need the GitHub API are left out, so resolve() stays offline.

• ecosystems – The language-package ecosystems to detect; defaults to the registered ones.

• repository (str)

• mise (Mise)

• platform (Platform | None)

• github (GitHub | None)

• ecosystems (Sequence[Ecosystem])

Returns:

The ranked candidates; the first is the recommendation.

When GitHub is unreachable or a mise probe fails, the other candidates are kept and the skipped steps are named in notes.

The first failure (GitHubUnavailableError or MiseError) is raised instead when a step failed and no step found a candidate, so the answer does not read as “no backend”.

An InvalidPlatformError is raised when no platform is given and the host is not a supported platform; an explicit platform needs no host detection.

Return type:

Resolution

The repository mibare is asked about, and how to recognise it in text.

class mibare.core.repository.Repository(owner, name)

Bases: object

A GitHub repository.

Parameters:

• owner (str)

• name (str)

owner

The account that owns the repository.

Type:

str

name

The repository name, without any .git suffix.

Type:

str

property shorthand: str

The owner/repo shorthand.

Returns:

The shorthand.

Return type:

str

mibare.core.repository.parse_repository(text)

Parse a GitHub URL or owner/repo shorthand.

Tolerates surrounding whitespace, trailing slashes, a .git suffix, a www. prefix, a missing scheme, extra path segments and a query or fragment (both ignored).

Parameters:

• text – The user’s input.

• text (str)

Returns:

The repository the input names.

Return type:

Repository

Raises:

InvalidRepositoryError – If the input does not name a GitHub repository.

The mise adapter: the only code that runs a mise binary (ADR 0002).

mise always runs in an isolated environment so the user’s settings, such as MISE_DISABLE_BACKENDS, never change the answer: a clean environment, a temporary HOME, MISE_NO_CONFIG=1, and GITHUB_TOKEN plus the proxy and certificate variables passed through so mise can still reach the network, and SystemRoot, which Windows needs in an explicit environment.

mibare.core.mise.MIN_MISE_VERSION = (2026, 10, 13)

The oldest mise whose registry --json output mibare understands.

class mibare.core.mise.Mise(*args, **kwargs)

Bases: Protocol

The interface resolve() needs from mise, replaceable in tests.

version()

Return the mise version, after checking it meets the minimum.

Return type:

str

registry()

Return the registry entries in registry order.

Return type:

tuple[RegistryEntry, …]

recipe_exists(backend_string)

Say whether mise can list versions of backend_string.

Raises:

MiseError – If the probe failed for a reason other than the recipe being absent, such as a network failure.

Parameters:

backend_string (str)

Return type:

bool

class mibare.core.mise.RegistryEntry(tool, backends)

Bases: object

One tool in mise’s registry.

Parameters:

• tool (str)

• backends (tuple[str, ...])

tool

The registry’s short name for the tool.

Type:

str

backends

The tool’s backend strings, in registry order.

Type:

tuple[str, …]

class mibare.core.mise.SubprocessMise(run=<function run_process>)

Bases: object

The real adapter, which runs mise as a subprocess.

Create the adapter.

Parameters:

• run – Runs the command line; replaced in tests so no process starts.

• run (Runner)

version()

Return the mise version, recording it on first use.

Returns:

The version number, such as 2026.10.13.

Return type:

str

Raises:

• MiseTooOldError – If mise is older than MIN_MISE_VERSION.

• MiseError – If the version cannot be read.

registry()

Return the registry entries in registry order.

Returns:

The entries from mise registry --json.

Return type:

tuple[RegistryEntry, …]

Raises:

MiseError – If mise is unusable or its output cannot be understood.

recipe_exists(backend_string)

Say whether mise can list versions of backend_string.

Parameters:

• backend_string – A backend string such as aqua:owner/repo.

• backend_string (str)

Returns:

True when mise ls-remote exits 0, False when it

reports the recipe as not found.

Return type:

bool

Raises:

MiseError – If mise ls-remote fails for any other reason, so a network or rate-limit failure never reads as “absent”.

mibare.core.mise.run_process(args, env, cwd)

Run a command with exactly env as its environment.

The executable is looked up on the caller’s PATH, not on env.

Parameters:

• args – The command and its arguments.

• env – The complete environment for the process.

• cwd – The directory to run in.

• args (Sequence[str])

• env (Mapping[str, str])

• cwd (Path)

Returns:

The finished process.

Return type:

subprocess.CompletedProcess[str]

Raises:

FileNotFoundError – If the executable is not on PATH.

Errors mibare reports to the user as exit code 2.

exception mibare.core.errors.GitHubUnavailableError

Bases: MibareError

The GitHub API could not be used: no network, a rate limit or a server error.

exception mibare.core.errors.InvalidPlatformError

Bases: MibareError

The platform is not a known os-arch pair.

exception mibare.core.errors.InvalidRepositoryError

Bases: MibareError

The input is not a GitHub URL or owner/repo shorthand.

exception mibare.core.errors.MibareError

Bases: Exception

Base class for errors with a message meant for the user.

exception mibare.core.errors.MiseError

Bases: MibareError

Running mise failed or its output could not be understood.

exception mibare.core.errors.MiseNotFoundError

Bases: MiseError

No mise binary is available.

exception mibare.core.errors.MiseTooOldError

Bases: MiseError

The mise binary is older than the minimum mibare supports.

exception mibare.core.errors.RepositoryNotFoundError

Bases: MibareError

GitHub has no repository with the given owner and name.

Configurations for the project.

class mibare.core.config.Settings(log_level=<factory>)

Bases: object

Application settings sourced from environment variables.

Stdlib-only fallback used when pydantic-settings is not enabled. Each field is overridable via an environment variable named after the uppercased project name (dashes normalized to underscores) plus the field, for example MIBARE_LOG_LEVEL.

Parameters:

log_level (str)

mibare.core.config.get_settings()

Return the cached settings singleton.

Cached so all callers share one instance; tests can reset or override it via get_settings.cache_clear() instead of patching an import-time value.

Returns:

The cached settings instance.

Return type:

Settings

Directory configurations for the project.

mibare.core.dirs.HOME_IS_RESOLVABLE: bool = True

Whether the user’s home directory could be resolved at import time.

When False the project has no user-owned directory to write to, so file logging is disabled in core/logging_setup.py rather than falling back to a predictable shared location.

mibare.core.dirs.ROOT_FOLDER_NAME: str = '.mibare'

Name of the root folder.

mibare.core.dirs.ROOT_FOLDER_PATH: Path = PosixPath('/home/runner/.mibare')

Path to the root folder.

mibare.core.dirs.LOG_FILE_PATH: Path = PosixPath('/home/runner/.mibare/main.log')

Path to the log file.

Set up logging for the project.

This module configures logging for the project, ensuring that log handlers are only added once to prevent duplicate log entries if the module is imported multiple times.

Setup is resilient to a read-only or unavailable $HOME: if the log directory cannot be created it degrades to console-only logging instead of raising, so read-only commands (--help, version) stay usable.

mibare.core.logging_setup.get_logger()

Return the cached project logger.

Returns:

The cached project logger.

Return type:

logging.Logger

mibare.core.logging_setup.setup_logger()

Set up and return the main logger for the project.

Ensures that handlers are only added once to avoid duplicate log entries if this module is imported multiple times.

Returns:

Configured logger for the project.

Return type:

logging.Logger

CLI (mibare.cli)

Thin Typer command-line wrapper around the library core.

CLI application for the project.

mibare <repo> is the whole interface: one command, no subcommands. It is a thin wrapper over mibare.core.resolve.resolve() that parses the argument, prints the resolution and maps the outcome onto an exit code.

mibare.cli.app.main(repository, *, platform=None, json_output=False, verbose=False)

Recommend which mise backend to install a GitHub repository with.

Exits 0 when a backend is found, 1 when none is, and 2 on an error such as input that is not a GitHub repository or a missing or too-old mise.

Example

mibare BurntSushi/ripgrep mibare https://github.com/BurntSushi/ripgrep

Raises:

typer.Exit – Always, with the exit code describing the outcome.

Parameters:

• repository (Annotated[str, <typer.models.ArgumentInfo object at 0x7f5b8dbe2850>])

• platform (Annotated[str | None, <typer.models.OptionInfo object at 0x7f5b8dbe2990>])

• json_output (Annotated[bool, <typer.models.OptionInfo object at 0x7f5b8dbe2ad0>])

• verbose (Annotated[bool, <typer.models.OptionInfo object at 0x7f5b8dbe2c10>])

Return type:

None