LimaCharlie Python SDK & CLI
Python SDK and command-line interface for the LimaCharlie endpoint detection and response platform.
- Documentation — CLI reference, SDK guide, authentication
- Platform Docs | REST API | Issues
Installation
pip install limacharlie
docker run refractionpoint/limacharlie:latest --help
The toon extra adds the TOON output format (limacharlie --output toon); every other format works with a default install.
pip install 'limacharlie[toon]'
On uv older than 0.12 the extra is not enough, because toon_format publishes only a pre-release and those versions resolve pre-releases for directly named requirements only. Name it directly there: uv tool install limacharlie --with 'toon-format>=0.9.0b1'. See the CLI output formats guide for details.
See Getting Started for Docker credential mounting and first steps.
Quick Start
limacharlie auth login --oid YOUR_ORG_ID --api-key YOUR_API_KEY
limacharlie auth whoami
limacharlie org info
limacharlie sensor list
See Authentication for OAuth, environments, credential resolution, JWT caching, and config directory migration.
Documentation
| Guide | Topics |
|---|---|
| Getting Started | Installation, Docker, first steps |
| Authentication | API keys, OAuth, environments, JWT caching, config migration |
| CLI Overview | Command pattern, output formats, filtering, discovery |
| SDK Overview | Architecture, setup, class reference |
Full reference: doc/README.md
Shell Completion
The CLI supports tab-completion for all commands, subcommands, and options.
Bash - add to ~/.bashrc:
eval "$(limacharlie completion bash)"
Zsh - add to ~/.zshrc:
eval "$(limacharlie completion zsh)"
Fish - run once:
mkdir -p ~/.config/fish/completions
limacharlie completion fish > ~/.config/fish/completions/limacharlie.fish
Restart your shell (or source the rc file) for completions to take effect.
Static completion files
If you prefer not to run eval on every shell start, you can write the completion script to a file once. This is slightly faster at shell startup but needs to be re-run after upgrading to pick up new commands and options.
Bash:
mkdir -p ~/.local/share/bash-completion/completions
limacharlie completion bash > ~/.local/share/bash-completion/completions/limacharlie
Zsh:
mkdir -p ~/.zfunc
limacharlie completion zsh > ~/.zfunc/_limacharlie
Ensure ~/.zfunc is in your fpath by adding this to ~/.zshrc (before compinit):
fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit
Development
Setup
git clone https://github.com/refractionPOINT/python-limacharlie.git
cd python-limacharlie
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
The editable install (-e) means changes to the source code take effect immediately without reinstalling.
Running the CLI
After the editable install, the limacharlie command is available in your venv:
limacharlie --version
limacharlie --help
limacharlie sensor list --help
Running Tests
Unit tests run without any credentials or network access:
# All unit tests
pytest tests/unit/ -v
# Single test file
pytest tests/unit/test_client.py -v
# Single test case
pytest tests/unit/test_client.py::TestClientInit::test_creates_with_explicit_creds -v
Integration tests require a real LimaCharlie organization:
pytest tests/integration/ --oid YOUR_ORG_ID --key YOUR_API_KEY -v
Building
pip install build && python -m build
pip install dist/limacharlie-*-py3-none-any.whl && limacharlie version
Releasing
Releases are published to PyPI automatically via GitHub Actions when a version tag is pushed. The package version is derived from the git tag using setuptools-scm — there is no hardcoded version to bump.
git tag 5.1.0
git push origin 5.1.0
The workflow runs unit tests, builds the package, and publishes to PyPI using Trusted Publishers (OIDC) — no API tokens or secrets required. See .github/workflows/publish-to-pypi.yml for details.
2 maintainers
Metadata
2 maintainers
Release files for limacharlie 5.8.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 | |
|---|---|---|---|---|
| limacharlie-5.8.0.tar.gz | 1.0 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| limacharlie-5.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.6 MB
Release files / limacharlie-5.8.0.tar.gz
| Download URL | limacharlie-5.8.0.tar.gz |
|---|---|
| Size | 1.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f9649630314536404b8dd875d64d97d8ff039e050909f280b73a9ca340c7ae59
|
|
BLAKE2b-256 checksum How to use checksums |
f674567b9f9a8163ed7e1af0d8ae57b683746db12a54fae53ba5e157793bddb1
|
| 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 Oct 13, 2026.
Transparency logRelease files / limacharlie-5.8.0-py3-none-any.whl
| Download URL | limacharlie-5.8.0-py3-none-any.whl |
|---|---|
| Size | 588.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c77114a67eaf3a86ac138f4fa2eed7c44ba17853b2f8f8f01f51c0905c736f4a
|
|
BLAKE2b-256 checksum How to use checksums |
864c90276cf9b64b2d8bd6ab852421316415f84b2c56319a20976709e8702d60
|
| 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 Oct 13, 2026.
Transparency logSecurity for limacharlie 5.8.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
All 2 files in this release have been uploaded with provenance metadata.
Attestation for limacharlie-5.8.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 Oct 13, 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.
