Skip to main content

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:

  • --url and --token override the matching environment variables.
  • --json emits machine-readable JSON.
  • --no-version-check skips 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)

Source distribution for annotateit-ai 0.1.0
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)

Table of built distributions (wheels) for annotateit-ai 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page