Install¶
canair is not on PyPI yet. Install it from a clone of the repository. You need
uv, a fast Python package and tool manager.
Install the CLI¶
git clone https://github.com/philipkocanda/canair.git
cd canair
uv tool install . # installs the `canair` command globally
canair --help # first run creates ~/.config/canair/ + a starter config.yaml
The first canair run creates your user config directory and a starter config.yaml.
Some interactive commands need a vehicle profile. For these, canair shows a first-run chooser.
You pick a bundled or discovered profile, or you create a new one. The chooser tells you where
profiles live (~/.config/canair/profiles/). It saves your choice as default_profile, so later
runs do not ask again. The chooser does not appear when input is piped or scripted. It also does
not appear when you pass --profile or set CANAIR_PROFILE.
Next: connect your dongle.
Try it without installing¶
To try canair without a global install, run it from the checkout:
uv run canair … runs the code in the current repository checkout. Use this command also when you
work on canair itself.
Inside a clone, make install (alias make setup) does the full bootstrap in one step. It sets
up Git LFS, runs uv sync, installs the git hooks, and runs uv tool install --reinstall .. Run
it again after a git pull to refresh the bare canair command.
make install first checks two things. uv must be version 0.13 or later. uv must also not choose a
pre-release Python. The clone pins Python 3.15 (.python-version). An older uv resolves that pin to
an old alpha, and the alpha fails to build PyYAML. If the check stops, it names the fix
(uv self update).
Point your writes somewhere durable¶
uv tool install copies canair into the tool environment of uv. The copy includes the profiles
that ship with canair. The copy is frozen. A reinstall (canair update) replaces it
completely. If you record a capture or edit a PID in a bundled profile with a bare canair,
your next update deletes that data. Decide once, before you start:
# You have the clone (you just used it to install) — keep profile data in it:
canair config set profiles_dir /path/to/canair/profiles
# Or take your own copy of a bundled profile:
canair profile adopt hyundai-ioniq-ae-ev
A profile that you create yourself (canair profile create, or the first-run chooser) is already
in ~/.config/canair/profiles/. This does not affect it.
canair warns you when a write lands in the snapshot. canair update lists what a reinstall would
delete. These warnings do not replace the one-time setting above. For details, see
Profiles → Where your writes
land.
Staying up to date¶
canair checks GitHub once a day for a newer release. The check runs in a background thread. It never blocks a command, and canair ignores network failures without a message. When a new version exists, canair prints a one-line notice. The notice links to the changelog and shows how to upgrade.
To upgrade, run one command. It checks out the latest release tag in your clone and reinstalls the CLI from it. The git-clone install stays intact.
canair update # check, confirm, then checkout <tag> + uv tool install . --reinstall
canair update --check # report current/latest + changelog only, change nothing
canair update --yes # skip the confirmation prompt (automation)
canair update --python 3.13 # reinstall on Python 3.13 instead of the newest
The command checks out the advertised release tag. It does not fast-forward main. The
installed code is therefore exactly the released version, without unreleased commits from the
branch. If canair cannot find the latest release tag (for example, GitHub is unreachable),
canair update reports that it is offline. It makes no changes and does not guess a version.
The reinstall also moves canair to the newest Python that meets two conditions. uv must be able to install it, and every dependency must have a prebuilt wheel for it. If you do not have that Python, uv downloads it. Without the update, uv keeps a tool on the Python that it first used. canair starts faster on Python 3.15 and later. A dependency without a wheel would build from source. That needs a compiler and can make canair slower, so the update waits for the wheels. If the reinstall on the new Python fails, the update tries again on your previous Python.
If canair cannot find your clone or uv (for example, you used a different install method), it
prints the exact manual commands. To stop the automatic check, set check_for_updates: false in
your config. You can also export CANAIR_NO_UPDATE_CHECK=1.
The two installs can drift out of sync¶
If you run uv tool install . and work in a clone, you have two copies of canair on the
machine:
- A bare
canairruns the installed snapshot (the tool environment of uv). It is the state at your lastuv tool install. uv run canairruns the repository working tree. It is the code that you checked out or edited.
The two copies drift when you edit the repository or pull commits that change the version. A bare
canair then reports the old version, and uv run canair reports the new one.
canair update reports which copy is running. It warns when the version of the installed
snapshot differs from pyproject.toml in the clone. canair status shows the same warning. If no
newer release exists but the copies have drifted, canair update offers a reinstall-only
resync (uv tool install <clone> --reinstall). This needs no network access and no tag
checkout. canair update --json includes the full install block (running_origin,
running_build, tool_version, clone_version, out_of_sync).
The version tells you which build you're running¶
The bare package version cannot tell builds apart. A release, a clone with local edits and a wheel
from a feature branch can all say 5.2.0. For this reason, canair --version (or -V) names the
branch and the short commit, unless the code is exactly a release (a clean tree at the v5.2.0
tag). It also says where the copy came from:
$ canair --version
# uv run in a clone, on `main` at commit 343b244 (".dirty" with uncommitted edits)
canair 5.2.0+main.343b244 (from source)
# uv tool install . from the same clone
canair 5.2.0+main.343b244 (local build 343b244, 2026-11-05 10:12 UTC)
# after canair update: a clean build of the release tag
canair 5.2.0 (local build 9f2c1d0, 2026-11-05 10:12 UTC)
# a wheel built by GitHub Actions
canair 5.2.0 (CI build 9f2c1d0, 2026-11-05 10:12 UTC)
A run from source reads its git checkout live. An installed copy reads the build stamp that the
build hook (hatch_build.py) writes into every wheel. The stamp holds the commit, branch, release
tag, dirty flag, build time and builder. A copy that you installed in another way has no stamp. It
says installed, no build info. canair update --json gives the structured form under
install.build. For a CI build, it includes the URL of the CI run.
The version string appears in canair status and canair update. It also appears in every
capture that you record. If a reading looks wrong, you can trace it to the exact code that made
it. Release comparisons ignore the suffix, so a development checkout still gets an accurate "up to
date" result.
Tab-completion (optional)¶
Completion covers subcommands, flags, and the ECU and PID names of your active profile:
Completion hooks the literal canair command word, so it does not work through uv run. If you
work from a checkout, activate the virtual environment first:
Git LFS (for raw-CAN logs)¶
Git stores large raw-CAN broadcast logs (.blf, .asc, .trc and the captures/can/ directory
of a profile) with Git LFS. Install Git LFS once. Then a clone fetches the
real log contents instead of pointer files:
Without Git LFS, the small bundled fixtures still work because they are plain git. A large committed log appears as an LFS pointer. See Broadcast frames → Storing raw-CAN logs for what Git commits and what canair fetches on demand.