limacharlie 5.6.1

Python SDK and CLI for the LimaCharlie endpoint detection and response platform

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.