aidecl

aidecl

Command-line tool for validating, converting, and creating AI Declaration (aidecl) files.

AI Declaration files describe how AI tools were used in the creation of software, datasets, documents, and other digital work. This CLI validates them against the schema with both structural (JSON Schema) and semantic checks.

Installation

pip install aidecl

For development:

git clone https://github.com/ai-declaration/cli.git
cd cli
pip install -e ".[dev]"

Quick Start

# Create a new declaration file
aidecl init --format yaml

# Edit aidecl.yaml with your project details

# Validate it
aidecl validate aidecl.yaml

Usage

validate

Check one or more declaration files against the schema:

aidecl validate aidecl.yaml
aidecl validate aidecl.json another.yaml
aidecl validate --verbose aidecl.yaml
aidecl validate --output-format json aidecl.yaml
aidecl validate --strict aidecl.yaml  # warnings become errors
aidecl validate --quiet aidecl.yaml    # only exit code, no output

Sample output:

PASS [yaml]: aidecl.yaml

FAIL [yaml]: aidecl.yaml
    Schema error at 'ai_usage.level': 'high' is not valid. Allowed values: 'none', 'minimal', 'moderate', 'significant', 'extensive'

convert

Convert between YAML and JSON:

aidecl convert aidecl.yaml -f json
aidecl convert aidecl.json -f yaml -o output.yaml

init

Create a template declaration file:

aidecl init
aidecl init --format json
aidecl init --output my-project.yaml

The init command auto-detects your project name and git config for sensible defaults.

Exit Codes

Output Formats

text (default): Human-readable colored output.

json: Machine-readable output per file:

{
  "file": "aidecl.yaml",
  "passed": true,
  "schema_errors": [],
  "semantic_errors": [],
  "warnings": ["declaration date is in the future: 2099-01-01"]
}

github-actions: Annotation format for CI:

::error file=aidecl.yaml::used is false but tools are listed
::warning file=aidecl.yaml::declaration date is in the future

Validation Rules

Schema checks

Validates structure against JSON Schema Draft 2020-12: required fields, types, enum values, string formats, conditional requirements (e.g. summary required when used: true).

Semantic checks

Integration

GitHub Actions

- name: Validate AI Declaration Format
  run: |
    pip install aidecl
    aidecl validate --output-format github-actions aidecl.yaml

Pre-commit framework

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/ai-declaration/cli
    rev: v0.1.0
    hooks:
      - id: aidecl

Git pre-commit hook

#!/bin/sh
aidecl validate aidecl.yaml --quiet

Related Standards

Related Projects

• schema: schema definition and examples
• web: web-based generator and validator

Shell Completions

Bash:

eval "$(register-python-argcomplete aidecl)"

Or add to your .bashrc for persistent completions.

Fish and Zsh: use argcomplete or generate completions manually from the --help output.

Privacy Note

The declared_by field identifies who made the declaration. For public repositories, consider using team names or roles instead of individual names.

Compatibility

Development

pip install -e ".[dev]"
pytest
pytest --cov

License

Apache-2.0. The bundled schema.json is from schema (CC BY-SA 4.0).