Common Meta Framework (cMeta/cX)

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. There is nothing to set up: it is ~/CMETA (%USERPROFILE%\CMETA on Windows) unless one of the variables below says otherwise. cMeta picks it each time it starts, 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 only when you would rather they shared one, or want the home somewhere other than ~/CMETA. 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

Updating cMeta and the repositories

cx --version says how cMeta was installed, prints the command that updates it, and warns when a newer release is out (cMeta 0.32.2 and later). Or pick Update above, with the route cMeta was installed with. The common cases:

uv tool upgrade cmeta                   # installed with "uv tool install" or the script
uv pip install -U cmeta                 # uv, inside the virtual environment
pip install -U cmeta                    # pip, inside the virtual environment
cx repo pull ctuninglabs@cmeta-aops     # a repository from "cx repo get": git pull + reindex

An install from git keeps the same version number between commits, so it is reinstalled rather than upgraded (uv tool install --force ..., pip install --force-reinstall ...). A specific version: uv tool install --force --with pip "cmeta[server]==0.32.2". If cx --version still shows the old version afterwards, another cx comes first on PATH: which -a cx (where cx on Windows). Every route in Updating cMeta.

Troubleshooting

cx: command not found

Right after the installer, open a new terminal window: PATH is only read when a window starts. Otherwise 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.

Windows: 'rem' is not recognized, or A parameter cannot be found that matches parameter name 'fLO'

Commands for cmd.exe are running in PowerShell. PowerShell's prompt starts with PS: pick Windows · PowerShell above and copy the block again. ('#' is not recognized is the same mix-up the other way round.)

winget: 0x8a15005e: The server certificate did not match any of the expected values

winget also queries the Microsoft Store source, and something on this machine or network — typically an antivirus or a proxy that inspects HTTPS — breaks that source's certificate pinning. The commands on this page and the installer pass --source winget, which leaves the Store out; add it to any other winget install that fails this way.

Windows: long paths are not enabled

The cmeta-aops tasks offer to switch them on for you, with an administrator prompt. If that does not work, open Settings > System > Advanced and turn on Enable long paths — or, on Windows 10, run reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f in a terminal opened as administrator — and run the command again.

Windows: An Application Control policy has blocked this file

Seen as ImportError: DLL load failed while importing unicodedata from cx, git failing to load libcurl-4.dll, or cxt.exe blocked by your organization's Device Guard policy. Smart App Control, on by default on new Windows 11 PCs, refuses every binary that is neither signed nor known to Microsoft: the interpreter uv downloads, uv's command shims, the DLLs of Git for Windows, and every program you compile. The fix is to turn it off: Settings > Privacy & security > Windows Security > App & browser control > Smart App Control settings > Off. The switch is one-way and the normal state of a development machine; afterwards cx, cxt and git work as installed. To keep it on instead, stay with signed components: install Python from the Microsoft Store and put cMeta on it — uv tool install --with pip "cmeta[server]" --python python.exe (the --python matters once uv has downloaded its own interpreter, which it prefers) — and fetch repositories without git: curl.exe -fLo cmeta-aops.zip https://github.com/ctuninglabs/cmeta-aops/archive/refs/heads/main.zip then cx repo unzip cmeta-aops.zip (the same two commands update it later). uv's command shims (cx.exe, cxt.exe) are unsigned launchers and can be blocked as well (blocked by your organization's Device Guard policy): the signed way in is the tool environment's own interpreter, "%APPDATA%\uv\tools\cmeta\Scripts\python.exe" -m cmeta ... — a cx.cmd on PATH with @"%APPDATA%\uv\tools\cmeta\Scripts\python.exe" -m cmeta %* gives cx back, and cxt <task> is cx task run <task>.

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.