Skip to main content

amca

One command that knows what to do in whatever directory you are standing in.

amca looks at the directory you are in, works out which of its plugins apply, and runs them. All the behaviour lives in plugins.

# examples
$ cd ~/code/renderer     # a C project
$ amca                   # meson plugin: configures, builds, tests and runs it
[setup] … [compile] … [install] … [test] … [run]

$ cd ~/code/scraper      # a shell script
$ amca                   # autoscript plugin: runs amca_auto_script.sh

Same keystroke everywhere. amca decides which plugin applies and hands it the arguments; it has no opinion about what a build is.


Install

pip install amca

That's all. It needs Python 3.10 or newer, and tab completion sets itself up the first time you run amca in a terminal (details). Upgrade with pip install -U amca.

If pip refuses with externally-managed-environment (Debian, Ubuntu, Homebrew Python), use pipx install amca instead. For the development version: pip install git+https://github.com/Delici0u-s/amca.

Uninstall:

amca completions --uninstall     # first, while amca can still find its files
pip uninstall amca
rm -rf ~/.config/amca ~/.local/state/amca

Two commands

amca ships two console scripts, split by lifetime:

amca run plugins, and everything scoped to a project or a single run
amcapl manage which plugins exist on this machine at all

They share global flags and configuration. amcapl is separate so amca --help stays short and so plugin management cannot be triggered by a stray argument during a build.

Command reference

amca [global flags] [command] [MARKER plugin-args …]

  (none) / run     run every enabled plugin that applies here
  new              create an amca root (.amca/) in this directory
  remove           delete the amca root
  root             show or manage root detection (show, ignore, unignore, clear-ignored)
  args PLUGIN      edit that plugin's per-project default arguments
  config           inspect or change settings
  plugins          list installed plugins and their markers
  completions      print, install or remove shell tab-completion
  doctor           check paths, config, plugins, tools; non-zero on a problem

amcapl [global flags] <command> [NAME …]

  list                 what is installed, and its marker
  install              fetch and enable
  enable | disable | toggle
  uninstall
  update               re-fetch (use after editing a local plugin source)
  call NAME -- ARGS    run one plugin directly, skipping should_load
  alias [NAME PLUGIN [ARGS…]]   list your marker aliases, or add/change one
  unalias NAME… | --all         remove alias(es)

Global flags: --config-dir --plugin-dir --depth --editor --marker-prefix --log-mode --log-level --log-prefix --on-error --on-missing --debug --version, plus --dry-run on amca. Flags apply to one run and never write to your config file — see Configuration.

Leave out the plugin names on install, uninstall, enable, disable, toggle or call and you get a picker. In the checkbox, space selects and enter confirms — enter on its own selects nothing.

Exit status: 0 success; a failing plugin's own status (1 for a plugin error, the tool's status when a build or script fails, 127 when a tool it needs isn't installed); 2 bad usage or bad configuration; 130 interrupted.


Plugins

A plugin decides whether it applies (should_load) and then does the work (load). amca runs every enabled plugin that applies.

Passing arguments to a plugin

Everything after a marker goes to that plugin, until the next marker:

amca ---example --show
amca ---autoscript deploy --dry

A marker is plugins.marker_prefix (default ---) plus the plugin's folder name, underscores written as dashes. amca plugins --markers prints the exact strings this directory accepts.

Naming a plugin runs only that plugin. With no markers, amca runs everything applicable — the usual case. Set plugins.marker_scope=all if you want a marker to add arguments without narrowing the run.

An unrecognised marker is an error, and it suggests the fix:

$ amca ---autoScr
amca: unknown plugin marker '---autoScr'
  did you mean: ---autoscript
  known markers: ---autoscript, ---meson

A bare -- stops marker parsing, for values that begin with the prefix. After a marker, it hands everything that follows to that plugin, markers included:

amca config set plugins.marker_prefix -- ----
amca ---autoscript -- ---not-a-marker

Avoid shell glob characters (* ? [ ] { } ~) in the prefix: your shell expands the marker before amca sees it, and config set warns if you try. ! is a bad idea too, since bash expands it as history.

Personal aliases give a plugin a shorter marker, for you only, optionally with arguments that act as if typed right after the plugin's marker:

amcapl alias as autoscript          # amca ---as deploy  = amca ---autoscript deploy
amcapl alias mr meson -n run        # amca ---mr -v      = amca ---meson -n run -v
amcapl alias                        # list them
amcapl unalias mr                   # remove one (--all for every one)

The plugin's own marker keeps working, and its .amca/args file still applies (before the alias's arguments). amcapl refuses an alias that is already a plugin's marker, points at another alias, or looks like a typo of an installed plugin. It asks before replacing an existing alias (-f skips the question), and warns about one for a plugin you haven't installed yet. If you install a plugin with an alias's name later, the plugin wins and amca doctor says so. Aliases are stored as the plugins.aliases setting.

Per-project default arguments

.amca/args/<plugin>.args, one argument per line, # for comments. They are placed before anything you type, so a project can pin a flag while a command-line flag still overrides it.

amca args meson        # opens it in $EDITOR
amca args meson --show

Where plugins live

Three different places, easy to conflate:

<config>/plugins/ installed — what actually runs. amcapl manages it; plugins.dir moves it.
plugins/amca_presets/ in this repo the three bundled with amca, so amcapl install works offline
anywhere you like yours

Your own plugins do not belong in this repo. Add a source:

amca config set plugins.sources builtin,/home/you/my-amca-plugins
amcapl install cargo
amcapl update cargo            # re-copy after editing

While iterating, skip the copy entirely. Every plugin in that directory counts as enabled for that one run:

amca --plugin-dir ~/my-amca-plugins ---cargo build

Writing a plugin

A plugin is a directory containing plugin.py with exactly one subclass of amca.api.Plugin:

from amca.api import Plugin, PluginContext, PluginError
from amca.core import proc


class cargo(Plugin):
    description = "cargo build/run"

    def should_load(self, ctx: PluginContext) -> bool:
        # Cheap — called for every enabled plugin on every invocation.
        return ctx.project_dir_info().has_file("Cargo.toml")

    def load(self, ctx: PluginContext) -> int:
        if ctx.dry_run:
            ctx.log.log("would run cargo build")
            return 0
        cargo = proc.resolve_tool("cargo", hint="install rustup")
        return proc.call([cargo, "build", *ctx.args], cwd=str(ctx.project_dir))

PluginContext carries args, working_dir, root, plugin_dir (your private per-project directory, already created), dirs, log, dry_run and cli_args.

  • args is the project's .amca/args/<plugin>.args defaults followed by what was typed after your marker. It is always a list. Parse this one.
  • cli_args is only what was typed: None when your plugin wasn't named, [] for a bare ---name. ctx.invoked is shorthand for cli_args is not None.

Optionally set amca_api = "3.1" on the class: the plugin API version you wrote against (amca.api.API_VERSION). An older amca then refuses the plugin with "upgrade amca" instead of failing on a missing attribute. The API only grows, so a plugin keeps working on every later amca. amcapl list and amca doctor show each plugin's version, and flag 2.x-style plugins, which still run through an adapter.

To load only when called by name, return ctx.invoked from should_load. Don't use bool(ctx.args): it is False for a bare marker and can be True without one when the project has a defaults file.

Import amca.api directly — amca is an installed package. Do not vendor copies of its internals. Raise PluginError for a clean message with no traceback. Return an exit status; 0 or None means success.

Subdirectories work and are namespaced per plugin, so two plugins can both have an _impl/ without colliding:

my-plugin/
    plugin.py
    _impl/
        __init__.py

Tab completion of your plugin's arguments works without extra code if load() parses ctx.args with argparse before doing anything else: during a tab press, amca runs load() with dry_run=True and stops it at that first parse_args/parse_known_args, then completes against the parser it caught. Nothing after that line runs. To skip running load() at all, return the parser from parser() instead:

    def parser(self) -> argparse.ArgumentParser:
        parser = argparse.ArgumentParser()
        parser.add_argument("--out").complete = "dirs"   # files | dirs | commands | none
        return parser

An argument's complete attribute can also be a function (current_word) -> [value, ...] or [(value, description), ...], for values only your plugin knows. Plugins that don't use argparse can define complete(self, ctx, words) instead, and completion = False keeps amca from ever running load() for completion. A plugin that hangs or prints during that capture just gets file-name completion; the wait is capped by completion.plugin_timeout_ms.

Start from the example plugin rather than from one of the real presets:

amcapl install example
amca ---example --show     # prints every PluginContext field and what it is for

Bundled plugins

Three, installed on demand with amcapl install NAME. None of them is privileged; they are ordinary plugins that happen to ship inside the wheel.

applies when does
example never — call it directly a commented plugin to copy: selection, --dry-run, PluginError, tool resolution, logging
autoscript amca_auto_script.* is present runs it, forwarding your arguments
meson a meson.build is present setup → reconfigure → compile → install → test → run
autoscript — details

Runs amca_auto_script[.sh|.bash|.zsh|.py] (.ps1/.bat/.cmd/.py on Windows) from the working directory, falling back to the project root.

amca ---autoscript new         # create one (asks which type); also n, --new
amca ---autoscript new -y      # create the default (.sh / .ps1) without asking
amca ---autoscript build       # forwarded to the script
amca ---autoscript -v build    # print the command first
amca ---autoscript -- --help   # forward --help verbatim

Its own options are only read before the first script argument, so amca ---autoscript build -v hands -v to your script.

A .py script runs on Linux, macOS and Windows alike, with the project's Python, never amca's own: --python PATH if given (a file, a venv or a command; keep it in .amca/args/autoscript.args), else the active $VIRTUAL_ENV, else a venv in the project (any folder with a pyvenv.cfg), else python3 on PATH (py -3 on Windows). -v and --dry-run say which.

meson — details

Needs meson, which needs ninja and a compiler.

amca ---meson                 # whole pipeline
amca ---meson compile         # one step
amca ---meson -s              # delete the build, then the whole pipeline
amca ---meson -w              # meson setup --wipe (keeps the build dir), then the pipeline
amca ---meson -n t -n e       # skip test and run (also: -nt -ne)
amca ---meson -m              # copy `cd <dir>` + the run command to the clipboard instead
amca ---meson -Ab="--buildtype=debug" -Ae="--verbose"   # `=` when the value starts with -
amca ---meson --print-template > meson.build

Loads wherever there is a meson.build, and reads it through the amca variable block. A meson.build without one is reported as an error that says what is missing:

amca_var__meson__version_behaviour = '2.0.1'
amca_var__meson__build_dir         = 'build'
amca_var__meson__executable_name   = 'myapp'
amca_var__meson__install_dir       = '../compiled'   # relative to build_dir

version_behaviour names the template contract. Each version keeps its own meaning, so a newer plugin never changes how an older project builds. A file with no version is read as a v1 project (build_dir_where, output_dir, output_name), with the v1 flags: -s is setup --wipe, -clear cleans, -Ab/-Ac/-Ae take several words, and the pipeline skips test unless you ask for it (amca ---meson test). v1's .sources_cache file is ignored, which costs one extra reconfigure on the first run.

reconfigure re-runs meson only when the set of source files changes — ninja handles content changes. .vscode/launch.json and .clangd are kept pointing at the current build directory.


Configuration

One JSON file. Four layers, lowest priority first:

built-in default  →  config file  →  AMCA_* env var  →  command-line flag

Only amca config set writes to disk. Command-line flags apply to that run and nothing else.

config state (logs, caches, first-run marker)
Linux/BSD $XDG_CONFIG_HOME/amca → ~/.config/amca $XDG_STATE_HOME/amca → ~/.local/state/amca
macOS ~/Library/Application Support/amca ~/Library/Caches/amca
Windows %APPDATA%\amca %LOCALAPPDATA%\amca

Override with --config-dir / $AMCA_CONFIG_DIR and $AMCA_STATE_DIR. amca config path prints the one actually in use.

amca config list --origin      # every setting, its value, and which layer won
amca config list --changed
amca config get plugins.marker_prefix
amca config set plugins.marker_prefix '+++'
amca config unset core.editor
amca config describe log.mode  # type, default, env var name
amca config edit

--origin answers "I changed it and nothing happened": it shows whether an env var is overriding your edit, whether the key is real (unknown keys are reported, not ignored), and which file is actually in use.

Hand-editing the JSON is fully supported — config set is a convenience. Nested and dotted keys both work. Every setting has an env var: plugins.marker_prefix → AMCA_PLUGINS_MARKER_PREFIX.

All settings
key default
core.debug false extra diagnostics and full tracebacks
core.greet false print a greeting on every invocation
core.editor $VISUAL/$EDITOR/nano editor for amca args
root.folder_name .amca marker directory identifying a project root
root.search_depth 5 how far up to look for it
root.ask_to_create true offer to create one (TTY only)
root.ignored_paths [] where not to ask; amca root ignore
log.mode console console, file, both, silent
log.level INFO INFO, SUCCESS, WARN, ERROR, FATAL
log.prefix none none, minimal, simple, normal, verbose
plugins.dir <config>/plugins where installed plugins live
plugins.enabled [] which may run; amcapl enable
plugins.marker_prefix ---
plugins.marker_scope selected selected or all
plugins.aliases {} your own short markers, e.g. as=autoscript,mr=meson -n run; easier with amcapl alias
plugins.on_error continue or abort
plugins.on_missing warn ignore, warn, abort
plugins.announce_loaded false log each plugin as it runs
plugins.sources builtin, github:… where amcapl install looks
completion.plugin_timeout_ms 1000 how long a tab press waits for a plugin's arguments; 0 turns that off

External tools

export AMCA_TOOL_MESON=/opt/meson/bin/meson
export AMCA_TOOL_NINJA=samu

Security

A plugin is arbitrary Python that runs as you, with no sandbox. amca imports plugin.py and calls it; it does not inspect, restrict or review what that code does. Treat installing a plugin exactly like curl … | sh.

Concretely:

  • amcapl install copies a directory from a source and enables it. The defaults are builtin (inside the wheel you already trust) and a GitHub repository. Anything you add to plugins.sources — a URL, a local path — becomes code that runs on your next amca.
  • should_load runs for every enabled plugin on every invocation, before you have named anything. An enabled-and-installed plugin therefore executes in every directory you type amca in, not only where it applies.
  • .amca/args/<plugin>.args is read from the project directory, so cloning an untrusted repository that contains a .amca/ directory hands that repo influence over the flags your plugins receive. Run amca args <plugin> --show before running amca in a repo you did not write.
  • Shell completion runs amca on every tab press: amca itself, by absolute path (or from PATH for packaged scripts), never anything from the project directory.

amca doctor lists every installed plugin, its plugin API version and whether it loads.

Shell completion

Nothing to do. The first time you run amca in a terminal, it sets up tab completion for the shell in $SHELL and says so once. Open a new terminal and it works. The setup has two parts:

  • the script, in the shell's per-user completion directory (~/.local/share/bash-completion/completions/amca, ~/.local/share/zsh/site-functions/_amca, ~/.config/fish/completions/amca.fish);
  • for bash and zsh, a delimited # >>> amca completion >>> block in ~/.bashrc / ~/.zshrc that loads it. zsh reads no per-user directory on its own, and bash reads that directory only through the bash-completion package, which minimal systems, macOS and many custom rc files don't load. fish needs no block.

The block works anywhere in the rc file, before or after your own compinit, and does nothing once the script is gone. amca refreshes both parts silently whenever an upgrade changes them, so they never go stale.

amca completions --status           # per shell: active, installed, system-wide or not
amca completions --install          # set it up now (or again), for $SHELL or a named shell
amca completions --install --no-rc  # script only; prints the block to add yourself
amca completions --uninstall        # removes script and rc block, and stops auto-setup
amca completions bash > somewhere   # just print it
export AMCA_NO_AUTO_COMPLETION=1    # opt out without uninstalling

A wheel cannot run code at install time (PEP 427), so pip, pipx and uv tool have no way to register completions. Only a distro package can, by putting the script into /usr/share/zsh/site-functions and similar, which every shell already reads. That's why completion "just works" for programs from dnf or apt. Every user-level install (pipx, uv, cargo) needs an rc line instead; amca writes it for you on first run.

Packaging amca (a distro package or a Homebrew formula): write the system-wide files into the package's share directory.

amca completions --package-into "$pkgdir/usr/share"   # all shells; name one to limit it

That writes bash-completion/completions/{amca,amcapl}, zsh/site-functions/_amca and fish/vendor_completions.d/{amca,amcapl}.fish. These scripts find amca on PATH instead of baking in a path. When a shell's file is present in a share dir on $XDG_DATA_DIRS (or next to the Python amca runs on), the first-run setup leaves that shell alone, and --status shows it as system-wide.

bash and fish autoload by command name, so amcapl gets its own file alongside amca's; zsh binds both from a single #compdef line.

Calling amca through a shell alias? The generated script calls amca by absolute path, so a venv install off PATH still completes, but a shell alias (not a plugin alias) needs registering:

amca completions --install --command a3        # an alias for amca
amca completions --install --pl-command ap     # an alias for amcapl

Aliases are remembered, so later refreshes keep them.

What completes: every command, subcommand, alias and flag, in the order they're defined (aliases share a line with their command in zsh); option values and choices; config keys with their descriptions, and the valid values for config set <key>; plugin names and markers; and, after a marker, the plugin's own flags and values, taken from the plugin's argparse parser (see Writing a plugin). amcapl call <plugin> completes that plugin's arguments too.

The installed scripts hold no knowledge of amca: each tab press runs amca __complete, which answers from the same parsers a real run uses. A new flag, plugin or marker prefix completes immediately, without regenerating anything, at the cost of one short amca start per tab press. Only the plugin whose marker is active gets loaded.

These print the same lists, for your own scripts:

amca plugins --names
amca plugins --markers
amca config list --keys

When something is wrong

amca doctor

Checks paths, which config layer each non-default setting came from, root resolution, every plugin's health, external tools, and the subprocess environment. Exits non-zero when it finds a problem. It is the right thing to paste into an issue.

Upgrading from amca 2.x
amca config migrate --dry-run     # show what would be imported
amca config migrate

Keys were renamed and several boolean pairs became enums:

2.x 3.x
args.plugin_prefix plugins.marker_prefix
generic.plugin_path plugins.dir
generic.exit_on_plugin_error plugins.on_error = continue|abort
generic.exit_on_plugin_not_found plugins.on_missing = ignore|warn|abort
logging.print_loaded plugins.announce_loaded
extreamly_important.greet_user core.greet

Then remove the old install before deleting the old checkout — the uninstaller is the only thing that knows to strip the # >>> amca PATH >>> block from your shell rc:

python install_uninstall_update.py uninstall --keep-config

Existing plugins keep working: the loader detects the old five-argument should_load(amca_root_dir, amca_root_plugin_dir, working_dir, dir_parser, args) and adapts it. Port them when convenient.

If you upgrade by extracting a release over an old checkout, note that unzipping does not delete removed files — amca doctor will tell you if a stale src/amca/presets/ is left behind.

Why 3.0 exists. 2.x shipped as a PyInstaller --onefile binary rebuilt at install time. That put a private copy of CPython on LD_LIBRARY_PATH for every child process, so after a distro Python upgrade the system meson loaded amca's stale libpython and died with internal Python C API version mismatch. 3.0 is a normal Python package, which makes that class of bug structurally impossible. Along the way: CLI flags no longer write to your config file; plugin markers have one definition instead of two disagreeing ones; root discovery no longer runs at import time; plugins import amca.api instead of vendoring internals; and two plugins can have identically named submodules without shadowing.

Development

git clone https://github.com/Delici0u-s/amca && cd amca
pip install -e '.[all,dev]'

pytest -q                    # unit tests, a few seconds
python tests/e2e.py          # end-to-end matrix, real subprocesses
python tests/e2e.py --list   # the matrix without running it
python tests/e2e.py -k markers -v
ruff check src tests plugins
mypy

Layout:

src/amca/              the application
plugins/amca_presets/  bundled plugins — content, not application code
tests/

tests/test_regressions.py holds one test per defect that shipped. Add to it rather than deleting from it. tests/e2e.py runs the real console scripts against throwaway config and project directories; cases marked ! exercise a mistake, hostile argv, or a broken component, and there are more of those than happy paths. tests/fixtures/probe/ is a plugin that dumps its whole PluginContext as JSON and can be driven into any failure mode with PROBE_* environment variables. tests/test_completion_scripts.py sources the generated shell scripts and drives the completion functions for real — emitting a script is not evidence that it completes anything.

Platform support

Linux fully tested
macOS code paths tested by simulation, not executed
Windows code paths tested by simulation, not executed

tests/test_platform.py patches os.name / sys.platform and reloads the affected modules to exercise the non-Linux branches: config directories, the .exe suffix, the autoscript interpreter table, non-POSIX shlex splitting, colour detection, read-only file deletion. That verifies the branches are correct and reachable — not that Windows behaves as expected.

Windows caveats: plugin folder names are matched case-sensitively, so keep them lowercase; ANSI colour needs Windows Terminal or a console accepting ENABLE_VIRTUAL_TERMINAL_PROCESSING; autoscript does not offer an extensionless script, since such a file is not executable there.

License

GPL-3.0-or-later. See LICENSE.

Metadata

Release files for amca 3.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for amca 3.1.1
File Size Uploaded Provenance Actions
amca-3.1.1.tar.gz 170.7 kB Without provenance Details for amca-3.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for amca 3.1.1
File Interpreter ABI Platform Actions
amca-3.1.1-py3-none-any.whl Python 3 none any Details for amca-3.1.1-py3-none-any.whl

Total release size: 314.0 kB

Release files / amca-3.1.1.tar.gz

Download URL amca-3.1.1.tar.gz
Size 170.7 kB
Tags Source
SHA-256 checksum
How to use checksums
4f340825d525566e59b9b030e84912f6078e666b8ef221c0a5083a67019f9d5e
BLAKE2b-256 checksum
How to use checksums
165d39eab332bfbd62f57726adc77b0d30c5b94a4cbb47000969572da5f60d1f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / amca-3.1.1-py3-none-any.whl

Download URL amca-3.1.1-py3-none-any.whl
Size 143.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
19ee987e40c8903d8af9cf2dca768fb844d0be3d978293c1f88a1242e234523e
BLAKE2b-256 checksum
How to use checksums
8fe90c3f9e47a0913e5b2c83e8fdc1da359598a1207ef9da49550f36a1d25448
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Security for amca 3.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page