Where cMeta puts everything

One directory — the cMeta home — holds repos.json, the plugged repositories under repos/, the fast lookup index under index/, and the task caches. cMeta picks it the first time it runs, in this order:

The practical consequence: activate a venv and cMeta follows it, so two projects can hold different repositories at different versions without either knowing about the other. Set CMETA_HOME when you would rather they shared one. Check which one is live at any moment with:

cx --version

… which prints the resolved home path along with the version. A one-off override without touching the environment is cx --home=<path> <category> <command>.

Serial or async — there is nothing to pick

cMeta can be driven serially (a script, the CLI, a CI step) or asynchronously from an event loop. Both modes use the same categories, artifacts and commands, and the async class needs no extra: CMetaAsync is built on asyncio and concurrent.futures from the standard library, so the plain install above is already enough to await cm.access(...).

from cmeta import CMeta, CMetaAsync

cm = CMeta()                       # serial
r = cm.access({'category': 'repo', 'command': 'list'})

cma = CMetaAsync()                 # same calls, awaited
r = await cma.access({'category': 'repo', 'command': 'list'})

The server extra above is only about the web stack you would host it in — FastAPI and uvicorn — not about async itself. There is also an async extra; it is deliberately empty and exists so cmeta[server] can reference it, which is why this page does not offer it as a choice. Several processes may share one cMeta home: file locks and atomic writes protect the index and the metadata.

After the install

A fresh engine ships one small internal repository and nothing else, so the first thing worth doing is plugging in content:

cx repo list                    # what is plugged in
cx category list                # what those repos can do
cx repo get --url=https://github.com/<org>/<repo>
cx --reindex                    # after editing artifacts by hand

Your own work goes in your own repository — create one anywhere and plug it in:

cx repo init my-repo
cx category add my-repo:my-category
cx my-category add my-first-artifact

Troubleshooting

cx: command not found

Python's Scripts (Windows) or bin (Linux, macOS) directory is not on PATH. Either activate the virtual environment, or call the module directly with python -m cmeta.

Repos keep disappearing between shells

The home moved with you. A venv that is active in one terminal and not in another resolves to two different homes — see the table above, and cx --version to see which one you are in.

uv pip install refuses to run

uv will not install into a global interpreter unless told to. Either activate a virtual environment, or add --system.

Lookups look stale after editing files by hand

Rebuild the index with cx --reindex. Editing only an artifact's payload needs no reindex — the index tracks metadata, not content.