Skip to main content

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

  1. Initialize config:
intent init
  1. 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.

  1. 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].assertions in intent.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)

Source distribution for intent-cli 0.1.3
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)

Table of built distributions (wheels) for intent-cli 0.1.3
File Interpreter ABI Platform Actions
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.

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