Installation and Setup

What version of Python do I need?

Python 3.12 or higher. licit uses StrEnum and other features that require 3.12+.

python3.12 --version
# If you don't have it:
# Ubuntu/Debian: sudo apt install python3.12
# macOS: brew install python@3.12
# Windows: download from python.org

Error: “pip install” hangs

If you are on a system with multiple Python versions, make sure you are using the correct pip:

# Incorrect (may use Python 3.10 or another version)
pip install licit-ai-cli

# Correct
python3.12 -m pip install licit-ai-cli

Error: ModuleNotFoundError: No module named 'licit'

The installation did not complete correctly. Reinstall:

python3.12 -m pip install -e ".[dev]"

Verify that the entry point works:

python3.12 -m licit --version

Configuration

Where does the .licit.yaml file go?

At the root of your project, alongside pyproject.toml or package.json:

my-project/
├── .licit.yaml      ← here
├── pyproject.toml
├── src/
└── tests/

Can I use a different name for the config file?

Yes, use the --config option:

licit --config my-config.yaml status

What happens if .licit.yaml has syntax errors?

licit logs a warning and uses default values. It does not fail with an error.

$ licit --verbose status
# Warning: Failed to parse .licit.yaml: ...
# Using default configuration

Should I commit .licit.yaml?

Yes. It is the shared team configuration. Commit .licit.yaml.

Do not commit .licit/provenance.jsonl or .licit/fria-data.json (sensitive data).

Commands

licit trace / licit changelog / licit fria do not work

These commands are registered in the CLI but their full implementation is part of future phases:

The functional commands in v0.1.0 are: init, status, connect.

licit init does not detect my language/framework

ProjectDetector looks for specific files:

If your language or framework is not supported, open an issue.

licit status shows “not collected” for provenance

This is normal in v0.1.0. Provenance collection is implemented in Phase 2. Run licit trace once available.

Testing and Development

Tests fail with structlog errors

Make sure tests/conftest.py configures structlog correctly:

import logging
import structlog

structlog.configure(
    wrapper_class=structlog.make_filtering_bound_logger(logging.CRITICAL),
    cache_logger_on_first_use=False,
)

The most common error is ValueError: I/O operation on closed file when Click’s CliRunner closes stderr and structlog tries to write to it. The solution is to use WriteLoggerFactory() (not PrintLoggerFactory(file=sys.stderr)).

mypy shows errors on future module imports

Imports from future-phase modules (like licit.provenance.store) use # type: ignore[import-not-found]:

from licit.provenance.store import (  # type: ignore[import-not-found]
    ProvenanceStore,
)

The type: ignore comment must be on the from line, not on the imported name lines. If ruff reformats the import to multiline, verify the comment ends up on the correct line.

ruff reports UP042 on my enums

Use StrEnum instead of (str, Enum):

# ruff UP042 error:
class MyEnum(str, Enum):  # ← error
    VALUE = "value"

# Correct:
from enum import StrEnum
class MyEnum(StrEnum):    # ← correct
    VALUE = "value"

How do I run a single test?

# By name
python3.12 -m pytest tests/test_cli.py::TestCLIHelp::test_help -q

# By pattern (keyword)
python3.12 -m pytest tests/ -q -k "test_init"

# By file
python3.12 -m pytest tests/test_core/test_project.py -q

Compliance

Does licit replace a lawyer/compliance consultant?

No. licit is an assistance tool that automates evidence collection and generates reports. Final compliance decisions must be reviewed by qualified professionals.

Is the licit report sufficient for an EU AI Act audit?

The licit report is a starting point. It provides structured technical evidence that can complement compliance documentation. For a formal audit, you will need:

1. Legal review of the FRIA
2. Additional organizational documentation
3. Evidence of risk management processes
4. Team training records

What if my project is not “high-risk” under the EU AI Act?

If your AI system does not fall into the high-risk category, many EU AI Act requirements do not apply. licit allows marking requirements as n/a (not applicable). However, it is good practice to comply with transparency (Art. 13) and human oversight (Art. 14) requirements regardless of risk classification.

Is OWASP Agentic Top 10 mandatory?

It is not regulation; it is a security best practices framework. However, following the OWASP Agentic Top 10 recommendations significantly reduces security risks when using AI agents in development.

Security

Does licit send data to any server?

No. licit operates 100% locally. There is no telemetry, analytics, or communication with external servers.

Can I use licit in an air-gapped environment?

Yes. licit does not require an internet connection to function. You only need to install the dependencies beforehand.

Is it safe to commit the generated reports?

Reports in .licit/reports/ are generally safe to commit. They contain compliance evaluations, not sensitive data. However, review the content before pushing to a public repo.

Files you should not commit:

• .licit/provenance.jsonl — Contains contributor information
• .licit/fria-data.json — May contain sensitive FRIA data
• Signing keys (.licit/signing-key)

Known Issues (v0.1.0)

Glossary