Getting started

Install

pip install decoct

Requires Python 3.10+. For development:

pip install -e ".[dev]"

For LLM-powered features (schema and assertion learning):

pip install decoct[llm]

Basic compression

decoct auto-detects 8 platforms including Docker Compose, Kubernetes, Ansible, cloud-init, Terraform state, GitHub Actions, Traefik, and Prometheus. Just point it at your config:

decoct compress docker-compose.yaml

This automatically applies the bundled schema for the detected platform. Secrets are redacted, comments stripped, and platform defaults removed.

Pipe from stdin:

cat docker-compose.yaml | decoct compress

See token savings:

decoct compress docker-compose.yaml --stats

services:
  web:
    image: nginx:1.25.3
    ports:
      - "8080:80"
Tokens: 142 → 58 (saved 84, 59.2%)

Use bundled schemas

25 schemas ship with the package. Use short names instead of file paths:

decoct compress config.yaml --schema docker-compose
decoct compress cloud-init.yaml --schema cloud-init
decoct compress terraform.tfstate --schema terraform-state
decoct compress deployment.yaml --schema kubernetes
decoct compress playbook.yaml --schema ansible-playbook
decoct compress prometheus.yml --schema prometheus

Or create your own schema file for custom platforms:

platform: docker-compose
source: Docker Compose specification v3.8
confidence: authoritative

defaults:
  services.*.restart: "no"
  services.*.network_mode: bridge
  services.*.privileged: false
  services.*.read_only: false

drop_patterns:
  - "**.uuid"

decoct compress config.yaml --schema schemas/my-platform.yaml

Add assertions

Assertions encode your design standards. Conformant must-severity values get stripped; deviations are annotated:

assertions:
  - id: no-latest
    assert: Image tags must not use latest
    match:
      path: services.*.image
      pattern: "^(?!.*:latest$)"
    rationale: Reproducible deployments
    severity: must

  - id: restart-policy
    assert: Containers must use unless-stopped
    match:
      path: services.*.restart
      value: unless-stopped
    rationale: Proper restart behaviour
    severity: must

Compress with both:

decoct compress config.yaml \
  --schema schemas/docker-compose.yaml \
  --assertions assertions/docker-services.yaml

Use a profile

Bundle schema, assertions, and pass config into a single profile:

name: docker-compose
schema: schemas/docker-compose.yaml
assertions:
  - assertions/docker-services.yaml
passes:
  strip-comments:
  strip-defaults:
    skip_low_confidence: true

Use a bundled profile by short name:

decoct compress config.yaml --profile docker-compose

Or pass a custom profile file:

decoct compress config.yaml --profile profiles/docker.yaml

INI and key-value files

decoct handles INI-style configuration files (.ini, .conf, .cfg, .cnf, .properties) with automatic section detection and type coercion. Output is always YAML.

decoct compress my.cnf --schema mariadb-mysql --stats

Learn schemas and assertions

Instead of writing schemas by hand, let Claude derive them from example configs or vendor documentation:

decoct schema learn -e prod-config.yaml -p my-platform -o schema.yaml
decoct assertion learn -s team-standards.md -p docker-compose -o assertions.yaml

Requires pip install decoct[llm] and the ANTHROPIC_API_KEY environment variable.

Compress directories

Pass a directory to compress all config files in it:

decoct compress ./config/
decoct compress ./config/ --recursive
decoct compress ./config/ --stats

Multi-file runs show per-file stats and aggregate totals. Supports .yaml, .yml, and .json files.

Inspect what was removed

decoct compress config.yaml --schema schema.yaml --show-removed

--- strip-secrets ---
  Removed: 2 items
  db.password (path_pattern)
  db.connection_string (regex:azure_connection_string)
--- strip-defaults ---
  Removed: 5 items
--- strip-conformant ---
  Removed: 3 items