charisma-cli
CLI tool that watches an allure-results directory during test execution and streams results + attachments to the Charisma ingestion API in real time.
Installation
pip install charisma-cli
No token, no index URL — works on any laptop and in any CI. The package is published to public PyPI; the Charisma repo itself stays private (only this client wheel is public).
For local development from a checkout of the repo:
pip install -e packages/charisma-cli
Publishing (maintainers)
Releases publish to public PyPI automatically from the merge-queue workflow using a PyPI API token.
Trusted publishing (OIDC) is not used because this repo runs on GitHub Enterprise Server, whose OIDC issuer PyPI does not trust. A stored API token is required instead.
One-time setup (done once by a PyPI project owner):
- Sign in to PyPI with the team-owned account (2FA enabled).
- Go to Account settings → API tokens → Add API token. Scope it to the
charisma-cliproject once the project exists; for the very first publish use an account-scoped token, then re-scope it to the project afterward. - Copy the token (starts with
pypi-). - In the GitHub Enterprise repo, add it as an Actions secret named
PYPI_API_TOKEN(org-level secret recommended so both packages share it). - Bump
versioninpyproject.tomland merge — the workflow builds and publishes on the next release.
Rotate the token periodically and store it in the team secret manager.
Usage
export CHARISMA_ENDPOINT=https://charisma.company.com
export CHARISMA_TOKEN=<your-service-token>
export CHARISMA_PROJECT_ID=my-project
charismactl watch --results allure-results -- uv run pytest -n 4 tests/
Environment Variables
| Variable | Required | Description |
|---|---|---|
CHARISMA_ENDPOINT |
Yes | Base URL of the Charisma API |
CHARISMA_TOKEN |
Yes | Service or CI bearer token |
CHARISMA_PROJECT_ID |
Yes | Project alias for result routing |
CHARISMA_RESULTS |
No | Path to allure-results (default: allure-results) |
CHARISMA_RUN_KEY |
No | Run identity / merge key (--run-key fallback) |
BUILD_ID |
No | CI build identifier (--build-id fallback; CHARISMA_BUILD_ID also honored) |
BUILD_PLAN_KEY |
No | Build plan key (--build-plan-key fallback; CHARISMA_BUILD_PLAN_KEY also honored) |
ENVIRONMENT |
No | Environment code (--environment fallback; CHARISMA_ENVIRONMENT also honored) |
COMPONENT |
No | Component alias (--component fallback; CHARISMA_COMPONENT also honored) |
SOURCE_URL |
No | CI/CD build link (--source-url fallback; CHARISMA_SOURCE_URL also honored) |
Flags
Both upload and watch accept the identical option set.
| Flag | Description |
|---|---|
--endpoint URL |
Charisma API endpoint (overrides CHARISMA_ENDPOINT) |
--token TOKEN |
Bearer token (overrides CHARISMA_TOKEN) |
--results PATH |
Allure results directory (overrides env var) |
--project ID |
Project alias (overrides env var) |
--silent |
Don't fail pipeline if upload errors occur |
--skip-too-big |
Skip result files larger than 2MB |
--component ALIAS |
Component alias within the project |
--source-url URL |
CI/CD build link for this run |
--build-plan-key K |
Explicit build plan key for resolution (forwarded as buildPlanKey) |
--build-id ID |
CI build identifier for this run (forwarded as buildId) |
--environment ENV |
Environment code (e.g. qat, prod), stored on the launch |
--run-key KEY |
Run identity / merge key (reruns + parallel workers share it) |
Launch URL in CI
charismactl prints the Charisma launch URL (Charisma launch: <url>) and, when running
in GitHub Actions, writes it as a step output named launch_url. Attach it to the job
summary or a Teams message:
- name: Run tests and stream to Charisma
id: charisma
run: charismactl watch --project my-project -- pytest tests/
- name: Add Charisma link to summary
if: always()
run: echo "[View Charisma launch](${{ steps.charisma.outputs.launch_url }})" >> "$GITHUB_STEP_SUMMARY"
# The same value can feed a Teams-notification step:
# text: "Results: ${{ steps.charisma.outputs.launch_url }}"
Rerun test plan
On a Charisma-triggered Bamboo rerun, fetch the plan of failed/broken variants before the test task (service token required; CI tokens cannot read launches):
charismactl testplan get --project "$PROJECT_UUID" --launch "$LAUNCH_UUID" \
[--statuses FAILED,BROKEN] --output testplan.json [--format json|pytest-args]
json(default): forpytest-charismaviaCHARISMA_TESTPLAN_PATH=testplan.json.pytest-args: one node ID per line forpytest @testplan.txt. Exits 1 if the plan is empty or has a test a node ID cannot express (an empty list runs the whole suite).
--endpoint/--token fall back to CHARISMA_ENDPOINT/CHARISMA_TOKEN. watch/upload
also forward Allure titlePath, which Charisma uses to store each result's node ID.
Read API
Alongside the write path (watch/upload), the package ships an importable read client for
querying launches, results, history, and attachments from Charisma's Phase-1 read API. The client
returns the server JSON verbatim (Charisma-native shapes — UUID ids, {items, total} envelopes,
per-endpoint casing). It performs no Allure reshaping and is fully decoupled from the upload
machinery.
Project id is a UUID in read mode
Read is project-scoped by the project UUID, not by the write-path projectAlias.
- Write path (
watch/upload):CHARISMA_PROJECT_ID/--projectis the project alias. - Read path (
CharismaReadClient): theproject_idargument must be the project UUID.
A non-UUID value (for example, passing the write alias to the read client) fails early with a
clear CharismaProjectIdError naming the UUID-vs-alias distinction — not a late, confusing 404.
Python read client
from charisma_cli.read_client import (
CharismaReadClient,
CharismaNotFoundError,
CharismaAuthError,
CharismaReadError,
)
# project_id MUST be the project UUID (NOT the write-path projectAlias).
client = CharismaReadClient(
endpoint="https://charisma.company.com",
token="<service-token>",
project_id="3f2504e0-4f89-41d3-9a0c-0305e82c3301",
)
# --- Launches -------------------------------------------------------------
# list_launches is newest-first (no sort param) and takes up to 9 filters.
page = client.list_launches(offset=0, limit=25, status="failed", branch="main")
for launch in page.items: # PaginatedLaunchList -> BaseLaunch items (snake_case attrs)
print(launch.id, launch.name)
print("total:", page.total)
launch = client.get_launch("8a1b...launch-uuid") # LaunchRecord (snake_case attrs)
stats = client.get_launch_statistic("8a1b...launch-uuid") # LaunchStatisticRecord -> .counts[]
# --- Results of a launch (tags/metadataTags/zephyrIds populated) -----------
results = client.list_launch_results(
"8a1b...launch-uuid",
offset=0,
limit=25,
sort_by="startedAt", # name|status|startedAt|createdAt|durationMs
sort_order="desc", # asc|desc
status="failed",
)
# --- A single result (tags/metadataTags/zephyrIds are always []) -----------
result = client.get_result("c4d5...result-uuid") # TestResultRecord
execution = client.get_result_execution("c4d5...result-uuid") # ExecutionRecord
# execution.id / .status / .steps / .beforeHooks / .afterHooks / .backgroundSteps / .attachments
# --- History (TestCaseHistoryRecord) ---------------------------------------
history = client.get_result_history("c4d5...result-uuid")
print(history.history_id, history.stability.passed_count)
# --- Attachments ----------------------------------------------------------
atts = client.list_result_attachments("c4d5...result-uuid") # PaginatedAttachments (.items/.total)
url = client.get_attachment_url("e6f7...attachment-uuid") # AttachmentUrl (.download_url/.file_name/.content_type)
content = client.get_attachment_content("e6f7...attachment-uuid") # AttachmentContent
# content.content / content.file_name / content.truncated — text-only, truncated=True past the 1 MB cap
# --- Paginate any {items, total} endpoint ----------------------------------
# iter_pages drives offset/limit for you, yielding every item once (page_size
# defaults to 100, the server cap). Pass the list method plus its kwargs.
for launch in client.iter_pages(client.list_launches, status="failed"):
print(launch.id)
for row in client.iter_pages(
client.list_launch_results, launch_id="8a1b...launch-uuid", status="failed"
):
print(row.name, row.status)
client.close() # or use the client as a context manager: `with CharismaReadClient(...) as client:`
All methods return typed Pydantic models (from charisma_cli.read_models) parsed from the server JSON — e.g. list_launches -> PaginatedLaunchList, get_launch -> LaunchRecord, get_result_history -> TestCaseHistoryRecord. Model attributes are uniform snake_case (launch.started_at, result.duration_ms, history.history_id), consistent with the rest of the package. The server's wire casing is handled by Pydantic aliases, not the attribute names: model_validate accepts the server body as-is, and model_dump(by_alias=True) / model_dump_json(by_alias=True) reproduce the exact server JSON (camelCase for most endpoints, snake_case for history). model_dump() without by_alias gives you snake_case. Datetime fields parse to datetime; models set extra="allow" so a new server field is preserved. Failures raise a typed error:
| Error | Raised on |
|---|---|
CharismaNotFoundError |
HTTP 404 — the launch/result/attachment does not exist |
CharismaAuthError |
HTTP 401/403 — token missing, invalid, or lacking access |
CharismaReadError |
base error — a 400 (e.g. an invalid sort value), a persistent 5xx after retries, or a transport failure. CharismaProjectIdError (non-UUID project_id) also subclasses it |
Transient failures (429/5xx/timeouts) are retried with backoff before surfacing as
CharismaReadError; terminal statuses (400/401/403/404) are raised immediately, not retried.
Attributes are snake_case; the wire is reproduced via aliases
Every model exposes uniform snake_case attributes — there is no per-endpoint attribute casing to remember. The server's on-the-wire casing still differs per endpoint (camelCase for launches/results/attachments, snake_case for get_result_history), but that lives in the Pydantic aliases, not the attribute names. So you always read launch.source_url, result.duration_ms, history.history_id; and if you need the exact server JSON back, dump with by_alias=True. This keeps the Python API consistent while the client stays a faithful mirror of the Phase-1 wire contract.
Attachment endpoints and the token type
get_attachment_url and get_attachment_content require a token the Attachments Lambda
accepts. These two endpoints were historically user-token-only (allowed_token_types=["user"]),
which rejected the CLI's service token. They have been widened to accept both user and service
tokens (["user", "service"], ADR-035 / FR-0), so a service token now works — client-side
these methods behave exactly like the others, with no token-type special-casing. The ci token type
remains excluded from these two endpoints.
Metadata
Release files for charisma-cli 0.6.1
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 |
|---|---|---|---|---|
| charisma_cli-0.6.1.tar.gz | 124.1 kB | Without provenance | Details for charisma_cli-0.6.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| charisma_cli-0.6.1-py3-none-any.whl | Python 3 | none | any | Details for charisma_cli-0.6.1-py3-none-any.whl |
Total release size: 180.0 kB
Release files / charisma_cli-0.6.1.tar.gz
| Download URL | charisma_cli-0.6.1.tar.gz |
|---|---|
| Size | 124.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5306632b1867e0042c53b245468850f9085540e63edac2e7322150637df03778
|
|
BLAKE2b-256 checksum How to use checksums |
a8e44c10ad31546f096f4da5773d16c7dcdcb685415c1f2b6490506f37dd4fd6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Release files / charisma_cli-0.6.1-py3-none-any.whl
| Download URL | charisma_cli-0.6.1-py3-none-any.whl |
|---|---|
| Size | 55.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
28645f786e3de1c89063ad06fc7eea5a114212437fdd3042651e718fe245dd42
|
|
BLAKE2b-256 checksum How to use checksums |
8cf8ed4289b28a402131d7e5758ddbf00fee50568abfaf8850a79bf197141941
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Security for charisma-cli 0.6.1
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.