AnnotateIt Python SDK and CLI
annotateit-ai is the typed Python SDK and command-line client for the local
AnnotateIt REST API. The project is currently alpha software and targets Python
3.10 or newer.
Three names are intentionally different:
| Purpose | Name |
|---|---|
| PyPI distribution | annotateit-ai |
| Python package | annotateit_ai |
| CLI command | annotateit |
The annotateit distribution name on PyPI is already owned by another project,
so installs and dependency declarations must use annotateit-ai.
Install
Install the CLI with:
pipx install annotateit-ai
For use as a library:
python -m pip install annotateit-ai
To install the current checkout instead:
Windows PowerShell
git clone https://github.com/AnnotateIt-AI/annotateit-python.git
cd annotateit-python
py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .
annotateit --help
If PowerShell blocks the activation script, either adjust the execution policy
for the current process or call .\.venv\Scripts\python.exe directly.
macOS zsh or bash
git clone https://github.com/AnnotateIt-AI/annotateit-python.git
cd annotateit-python
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
annotateit --help
Python 3.10 or newer is supported. CI exercises the minimum version and the current stable Python 3.14 on Windows, macOS, and Ubuntu.
Connect to AnnotateIt
The default endpoint is http://127.0.0.1:8420/api/v1. A bare port, host URL,
or complete /api/v1 URL can be supplied through ANNOTATEIT_URL or --url.
Authenticated commands also need ANNOTATEIT_TOKEN or --token.
PowerShell:
$env:ANNOTATEIT_URL = "8420"
$env:ANNOTATEIT_TOKEN = "replace-with-your-token"
annotateit doctor
annotateit projects list
macOS:
export ANNOTATEIT_URL="8420"
export ANNOTATEIT_TOKEN="replace-with-your-token"
annotateit doctor
annotateit projects list
Command-line values take precedence over environment variables. Avoid putting a token directly on a shared machine's command line because it can be retained in shell history or visible to other processes.
CLI
Commands follow the resource layout of the API:
annotateit status
annotateit product info
annotateit projects list
annotateit datasets list <project-id>
annotateit media list <project-id> <dataset-id>
annotateit annotations get <project-id> <dataset-id> <media-id>
annotateit versions list <project-id> <dataset-id>
annotateit split show <project-id> <dataset-id>
annotateit quality show <project-id> <dataset-id>
annotateit openapi show
Use annotateit --help or append --help to a command for its exact arguments.
The CLI also covers tracks, frame annotations, imports, exports, project
activity, split planning, and quality scans.
Useful global options are:
--urland--tokenoverride the matching environment variables.--jsonemits machine-readable JSON.--no-version-checkskips the API compatibility preflight when connecting to an older server.
Lists that expose server cursors are fetched across pages automatically. Use the command-specific page-size and maximum-item options to cap large results.
Commands that delete or replace data require --yes. Downloads and generated
files refuse to replace an existing destination unless --force is present.
JSON request bodies accept --from path.json; use --from - to read UTF-8 JSON
from standard input. Downloads are written through a temporary file and moved
into place only after a successful response.
Examples:
annotateit projects create --name "Road signs" --task-type Detection
annotateit media upload <project-id> <dataset-id> ./frame.jpg
annotateit export <project-id> <dataset-id> --format coco --out dataset-coco.zip
annotateit annotations replace <project-id> <dataset-id> <media-id> --from annotations.json --yes
annotateit openapi show --out annotateit-openapi.json
Python SDK
The client can use the same environment variables as the CLI:
from annotateit_ai import Client
with Client() as client:
response = client.call("listProjects")
print(response)
Typed resource helpers are also available on client.projects,
client.datasets, client.media, client.annotations, client.tracks,
client.versions, client.splits, client.quality, and client.system.
For explicit configuration:
from annotateit_ai import Client
with Client("http://127.0.0.1:8420", "replace-with-your-token") as client:
project = client.projects.get("project-id")
Development and CI
Install the development tools with python -m pip install -e ".[dev]".
The local preflight creates isolated temporary environments, runs the same
quality gates as CI, builds both distributions, checks their metadata, installs
the wheel, and smoke-tests the console entry point.
PowerShell:
.\scripts\preflight.ps1
macOS or Linux:
bash scripts/preflight.sh
Pass a Python executable to select a version:
.\scripts\preflight.ps1 -Python C:\Python310\python.exe
bash scripts/preflight.sh python3.10
GitHub Actions runs the same lint, formatting, strict type checking, tests,
package build, twine check, and wheel smoke test for Python 3.10 and 3.14 on
windows-latest, macos-15, and ubuntu-latest.
Releases
PyPI publication uses GitHub's pypi environment and PyPI Trusted Publishing;
the repository does not store a PyPI API token. Publishing a non-prerelease
GitHub Release runs the full quality gates again, verifies the wheel and source
distribution, and then publishes them with provenance attestations. The release
tag must be v<version> and match both pyproject.toml and
src/annotateit_ai/_version.py.
License
Licensed under the Apache License 2.0.
Metadata
Release files for annotateit-ai 0.1.0
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 |
|---|---|---|---|---|
| annotateit_ai-0.1.0.tar.gz | 64.4 kB | With provenance | Details for annotateit_ai-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| annotateit_ai-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for annotateit_ai-0.1.0-py3-none-any.whl |
Total release size: 123.8 kB
Release files / annotateit_ai-0.1.0.tar.gz
| Download URL | annotateit_ai-0.1.0.tar.gz |
|---|---|
| Size | 64.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f9fcc8931a00d8c627cdac5a81d822f34151bc96afb9865cc67657ae1eedf6c4
|
|
BLAKE2b-256 checksum How to use checksums |
7bf1a750c29cc4d77e78f616b0e86713dbd0f6ca19f169cf95a2c4fdce46b9dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 18, 2026.
Transparency logRelease files / annotateit_ai-0.1.0-py3-none-any.whl
| Download URL | annotateit_ai-0.1.0-py3-none-any.whl |
|---|---|
| Size | 59.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
38bb662ce7471a75c82fb58a0f790b87fc5afdf2c3d6ef62fd9667a8c4f4367c
|
|
BLAKE2b-256 checksum How to use checksums |
53e4f278c3474b04d942ce3ad6c7a23ab0420520876298eefbc94bdbbe829d9d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 18, 2026.
Transparency logSecurity for annotateit-ai 0.1.0
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for annotateit_ai-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 18, 2026.
Transparency logA 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.