civex

A local-first, command-line research data management system. Define schemas, collect records into collections, attach files, and automate processing with workflows — all on your own machine, with an optional web UI and HTTP server.

flowchart LR
    S[Schema] -->|defines| R[Record]
    R -->|stored in| C[Collection]
    R -->|has| F["Files<br>(content-addressed objects)"]
    R -->|triggers| W[Workflow jobs]

Install

pipx install civex

See Install for installing and updating (civex update).

60-second example

civex init
civex schema create trial --description "A single experimental trial"
civex schema add-field trial subject --type string --required
civex collection create study-2024
civex record add --to study-2024 --schema trial
civex serve                          # open http://localhost:8000

Take the five-minute tour for the full walkthrough, including workflows.

Documentation

Full docs live in docs/ — run make docs to browse them locally with live reload.

• Getting started — install, your first project, five-minute tour
• Guides — schemas & fields, collections & records, files, workflows, automation, server & web UI, remote sync, PostgreSQL, logging & telemetry
• Reference — built-in plugins (see the docs site's Reference section), writing a plugin, container plugins, wire protocol, plugin SDK
• Contributing — maintainer docs (dev setup, architecture, testing, release process) live in docs/contributing/ in the repository, alongside CONTRIBUTING.md

Development

make install   # uv sync — sets up the venv and dependencies
make check     # everything CI runs: format, lint, typecheck, test, docs build

See docs/contributing/dev-setup.md in the repository for the full local development workflow.

License

civex is free to use for any purpose, including commercial use. Redistribution and modification are not permitted. See LICENSE for full terms.