Intent
Intent keeps project automation config in sync from a single intent.toml.
- Source of truth:
intent.toml - Reads:
intent.toml,pyproject.toml - Generates baseline tool-owned files:
.github/workflows/ci.yml,justfile
Full reference: documentation.md
Install
From PyPI:
python -m pip install intent-cli
From source:
python -m pip install -e .
Quick Start
- Initialize config:
intent init
- Generate files:
intent sync --write
This bootstraps a baseline CI workflow and justfile from your intent.toml.
If you configure [checks].assertions, intent check evaluates typed JSON assertions on command output.
If you configure [[ci.jobs]], Intent generates workflow jobs from typed job/step definitions instead of the baseline single-job template.
If you configure [[ci.artifacts]], Intent generates upload steps for actions/upload-artifact.
If you configure [ci.summary], Intent can publish a built-in markdown summary to GITHUB_STEP_SUMMARY.
- Verify drift in CI/pre-commit:
intent check --strict
Minimal intent.toml
[intent]
schema_version = 1
[python]
version = "3.12"
[commands]
test = "pytest -q"
lint = "ruff check ."
eval = "cat metrics.json"
[checks]
assertions = [
{ command = "eval", path = "summary.score", op = "gte", value = 0.9 }
]
[ci]
install = "-e .[dev]"
[policy]
pack = "default"
strict = false
Common Commands
| Command | Purpose |
|---|---|
intent init |
Create starter config. |
intent init --from-existing |
Infer Python version from pyproject.toml when possible. |
intent init --starter tox |
Generate tool-owned tox.ini starter (reuses existing intent.toml). |
intent init --starter nox |
Generate tool-owned noxfile.py starter (reuses existing intent.toml). |
intent sync |
Show config + version checks. |
intent sync --show-json |
Print resolved sync config as JSON. |
intent sync --show-json --explain |
Include generated-file mapping details in JSON. |
intent sync --explain |
Show text mapping from intent config to generated blocks. |
intent sync --dry-run |
Preview file changes without writing. |
intent sync --write |
Write generated files. |
intent sync --write --adopt |
Adopt matching non-owned generated files. |
intent sync --write --force |
Force-overwrite non-owned generated files. |
intent check |
Detect drift without writing. |
intent check --format json |
Machine-readable drift report. |
intent doctor |
Diagnose issues with actionable fixes. |
intent reconcile --plan |
Preview Python-version reconciliation. |
intent reconcile --apply --allow-existing |
Apply reconciliation including existing-file edits. |
Typed CI Jobs
[commands]
lint = "ruff check ."
test = "pytest -q"
[[ci.jobs]]
name = "lint"
steps = [{ uses = "actions/checkout@v4" }, { command = "lint" }]
[[ci.jobs]]
name = "test"
needs = ["lint"]
timeout_minutes = 20
matrix = { python-version = ["3.11", "3.12"] }
steps = [
{ uses = "actions/setup-python@v5", with = { python-version = "${{ matrix.python-version }}" } },
{ command = "test", continue_on_error = false }
]
CI Artifacts
[ci]
artifacts = [
{ name = "junit", path = "reports/junit.xml", retention_days = 7, when = "on-failure" },
{ name = "coverage", path = "coverage.xml", when = "always" }
]
CI Summary
[ci.summary]
enabled = true
title = "Quality Report"
include_assertions = true
metrics = [
{ label = "score", command = "eval", path = "metrics.score", baseline_path = "metrics.prev_score", precision = 3 }
]
Safety Model
- Writes only tool-owned files in normal sync flow.
- Refuses unsafe overwrite unless explicitly requested.
- Supports explicit ownership modes:
strict,adopt,force. - Uses stable error codes (
INTENTxxx) for automation. - Supports typed quality assertions via
[checks].assertionsinintent.toml.
Pre-commit Hook
repos:
- repo: local
hooks:
- id: intent-check
name: intent check
entry: intent check --strict
language: system
pass_filenames: false
License
MIT
Metadata
Release files for intent-cli 0.1.3
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 |
|---|---|---|---|---|
| intent_cli-0.1.3.tar.gz | 34.8 kB | Without provenance | Details for intent_cli-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| intent_cli-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for intent_cli-0.1.3-py3-none-any.whl |
Total release size: 60.8 kB
Release files / intent_cli-0.1.3.tar.gz
| Download URL | intent_cli-0.1.3.tar.gz |
|---|---|
| Size | 34.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3365999a65691b43751a28ff8f91ed52f5a96f9f224860712c8bafdd8a4692de
|
|
BLAKE2b-256 checksum How to use checksums |
eb0dd862c0e54f4e294c8b588f7ba87a5da2c1b714aa4b0f813052c129cc266d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / intent_cli-0.1.3-py3-none-any.whl
| Download URL | intent_cli-0.1.3-py3-none-any.whl |
|---|---|
| Size | 26.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b3b2a7e74502dcc239219dfb4baa3238c8909cff2f8f9e1c893b2d14795e97e1
|
|
BLAKE2b-256 checksum How to use checksums |
5359a5d94b24e5975252c728403ab96f99289cedb191e638fbbd1603f4cedda5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for intent-cli 0.1.3
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.