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 · Two commands · Command reference
- Plugins · Writing a plugin · Bundled plugins
- Configuration · Security · Shell completion
- Troubleshooting · Development · Platform support
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.
argsis the project's.amca/args/<plugin>.argsdefaults followed by what was typed after your marker. It is always a list. Parse this one.cli_argsis only what was typed:Nonewhen your plugin wasn't named,[]for a bare---name.ctx.invokedis shorthand forcli_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 installcopies a directory from a source and enables it. The defaults arebuiltin(inside the wheel you already trust) and a GitHub repository. Anything you add toplugins.sources— a URL, a local path — becomes code that runs on your nextamca.should_loadruns for every enabled plugin on every invocation, before you have named anything. An enabled-and-installed plugin therefore executes in every directory you typeamcain, not only where it applies..amca/args/<plugin>.argsis 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. Runamca args <plugin> --showbefore running amca in a repo you did not write.- Shell completion runs
amcaon every tab press: amca itself, by absolute path (or fromPATHfor 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/~/.zshrcthat 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.