# ITS Compiler CLI
[](https://pypi.org/project/its-compiler-cli/)
[](https://pypi.org/project/its-compiler-cli/)
[](LICENSE)
Command-line interface for the [ITS Compiler Python](https://github.com/alexanderparker/its-compiler-python) library. Converts [Instruction Template Specification (ITS)](https://alexanderparker.github.io/instruction-template-specification/) templates into structured AI prompts.
## Installation
```bash
pip install its-compiler-cli
```
This automatically installs the core [its-compiler](https://github.com/alexanderparker/its-compiler-python) library as a dependency.
## Quick Start
### Basic Usage
```bash
# Compile template to stdout
its-compile template.json
# Save output to file
its-compile template.json --output prompt.txt
# Use custom variables
its-compile template.json --variables vars.json
# Validate template without compiling
its-compile template.json --validate-only
```
### Example Template
Create `example.json`:
```json
{
"version": "1.0.0",
"extends": ["https://alexanderparker.github.io/instruction-template-specification/schema/v1.0/its-standard-types-v1.json"],
"variables": {
"topic": "renewable energy"
},
"content": [
{
"type": "placeholder",
"instructionType": "paragraph",
"config": {
"description": "Write about ${topic}",
"tone": "informative"
}
}
]
}
```
Compile it:
```bash
its-compile example.json
```
## Command Reference
```
its-compile [OPTIONS] TEMPLATE_FILE
Arguments:
TEMPLATE_FILE Path to the ITS template JSON file
Options:
-o, --output FILE Output file (default: stdout)
-v, --variables FILE JSON file with variable values
-w, --watch Watch template file for changes
--validate-only Validate template without compiling
--verbose Show detailed output
--strict Enable strict validation mode
--no-cache Disable schema caching
--timeout INTEGER Network timeout in seconds (default: 30)
--allow-http Allow HTTP URLs (not recommended)
--interactive-allowlist / --no-interactive-allowlist
Enable/disable interactive schema prompts
--allowlist-status Show schema allowlist status
--version Show version and exit
--help Show help and exit
```
## Development Workflow
### Watch Mode
Automatically recompile when the template changes:
```bash
its-compile template.json --watch --output prompt.txt
```
### Validation
Check templates for errors without compiling:
```bash
its-compile template.json --validate-only --strict
```
### Variables
Use external variable files:
```bash
# vars.json
{
"productName": "Widget Pro",
"features": ["fast", "reliable", "secure"]
}
its-compile template.json --variables vars.json
```
## Schema Management
When templates reference external schemas, you may be prompted to allow them:
```
SCHEMA ALLOWLIST DECISION REQUIRED
URL: https://example.com/schema.json
1. Allow permanently (saved to allowlist)
2. Allow for this session only
3. Deny (compilation will fail)
```
### Allowlist Commands
```bash
# Check current allowlist status
its-compile --allowlist-status
# Non-interactive mode (useful for CI/CD)
its-compile template.json --no-interactive-allowlist
```
## Configuration
Set environment variables to configure default behaviour:
```bash
export ITS_INTERACTIVE_ALLOWLIST=false # Disable prompts
export ITS_REQUEST_TIMEOUT=60 # Increase timeout
export ITS_ALLOWLIST_FILE=/path/to/allowlist.json
```
## Error Examples
### Missing Variable
```
✗ Variable Error: Undefined variable '${productName}'
Available variables: topic, features
```
### Invalid Template
```
✗ Validation Error: Missing required field 'version'
At: root
```
### Schema Issues
```
✗ Schema Error: Failed to load schema
URL: https://example.com/schema.json
```
## Testing
Test your CLI installation:
```bash
# Basic functionality test
echo '{"version":"1.0.0","content":[{"type":"text","text":"Hello"}]}' | its-compile /dev/stdin
# Download test runner (optional)
curl -O https://raw.githubusercontent.com/AlexanderParker/its-compiler-cli-python/main/test_runner.py
python test_runner.py
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes and add tests
4. Ensure all tests pass (`python test_runner.py`)
5. Run linting (`black . && flake8`)
6. Commit your changes
7. Push to the branch and open a Pull Request
### Development Setup
```bash
# Clone and setup
git clone https://github.com/AlexanderParker/its-compiler-cli-python.git
cd its-compiler-cli-python
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e ".[dev]"
# Run tests
python test_runner.py
```
### For Maintainers
**Publishing to PyPI:**
This package is published to PyPI as `its-compiler-cli`. Releases are currently managed manually:
```bash
# Build the package
python -m build
# Test upload to TestPyPI first (recommended)
python -m twine upload --repository testpypi dist/*
# Upload to production PyPI (requires appropriate credentials)
python -m twine upload dist/*
```
**TestPyPI Testing:**
```bash
# Install from TestPyPI to verify the package
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ its-compiler-cli
```
## Related Projects
- **[ITS Compiler Python](https://github.com/alexanderparker/its-compiler-python)** - Core library
- **[Instruction Template Specification](https://alexanderparker.github.io/instruction-template-specification/)** - Official specification
- **[ITS Example Templates](https://github.com/AlexanderParker/its-example-templates)** - Example templates
## License
MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "its-compiler-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Alexander Parker <pypi@parker.im>",
"keywords": "its, instruction, template, specification, ai, prompt, cli, command-line, compilation",
"author": null,
"author_email": "Alexander Parker <pypi@parker.im>",
"download_url": "https://files.pythonhosted.org/packages/b7/c5/a3c2d60c0112baa42c0ed420d002b0984c7f03c42d1e3887ea1f3da81100/its_compiler_cli-1.0.4.tar.gz",
"platform": null,
"description": "# ITS Compiler CLI\r\n\r\n[](https://pypi.org/project/its-compiler-cli/)\r\n[](https://pypi.org/project/its-compiler-cli/)\r\n[](LICENSE)\r\n\r\nCommand-line interface for the [ITS Compiler Python](https://github.com/alexanderparker/its-compiler-python) library. Converts [Instruction Template Specification (ITS)](https://alexanderparker.github.io/instruction-template-specification/) templates into structured AI prompts.\r\n\r\n## Installation\r\n\r\n```bash\r\npip install its-compiler-cli\r\n```\r\n\r\nThis automatically installs the core [its-compiler](https://github.com/alexanderparker/its-compiler-python) library as a dependency.\r\n\r\n## Quick Start\r\n\r\n### Basic Usage\r\n\r\n```bash\r\n# Compile template to stdout\r\nits-compile template.json\r\n\r\n# Save output to file\r\nits-compile template.json --output prompt.txt\r\n\r\n# Use custom variables\r\nits-compile template.json --variables vars.json\r\n\r\n# Validate template without compiling\r\nits-compile template.json --validate-only\r\n```\r\n\r\n### Example Template\r\n\r\nCreate `example.json`:\r\n\r\n```json\r\n{\r\n \"version\": \"1.0.0\",\r\n \"extends\": [\"https://alexanderparker.github.io/instruction-template-specification/schema/v1.0/its-standard-types-v1.json\"],\r\n \"variables\": {\r\n \"topic\": \"renewable energy\"\r\n },\r\n \"content\": [\r\n {\r\n \"type\": \"placeholder\",\r\n \"instructionType\": \"paragraph\",\r\n \"config\": {\r\n \"description\": \"Write about ${topic}\",\r\n \"tone\": \"informative\"\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\nCompile it:\r\n\r\n```bash\r\nits-compile example.json\r\n```\r\n\r\n## Command Reference\r\n\r\n```\r\nits-compile [OPTIONS] TEMPLATE_FILE\r\n\r\nArguments:\r\n TEMPLATE_FILE Path to the ITS template JSON file\r\n\r\nOptions:\r\n -o, --output FILE Output file (default: stdout)\r\n -v, --variables FILE JSON file with variable values\r\n -w, --watch Watch template file for changes\r\n --validate-only Validate template without compiling\r\n --verbose Show detailed output\r\n --strict Enable strict validation mode\r\n --no-cache Disable schema caching\r\n --timeout INTEGER Network timeout in seconds (default: 30)\r\n --allow-http Allow HTTP URLs (not recommended)\r\n --interactive-allowlist / --no-interactive-allowlist\r\n Enable/disable interactive schema prompts\r\n --allowlist-status Show schema allowlist status\r\n --version Show version and exit\r\n --help Show help and exit\r\n```\r\n\r\n## Development Workflow\r\n\r\n### Watch Mode\r\n\r\nAutomatically recompile when the template changes:\r\n\r\n```bash\r\nits-compile template.json --watch --output prompt.txt\r\n```\r\n\r\n### Validation\r\n\r\nCheck templates for errors without compiling:\r\n\r\n```bash\r\nits-compile template.json --validate-only --strict\r\n```\r\n\r\n### Variables\r\n\r\nUse external variable files:\r\n\r\n```bash\r\n# vars.json\r\n{\r\n \"productName\": \"Widget Pro\",\r\n \"features\": [\"fast\", \"reliable\", \"secure\"]\r\n}\r\n\r\nits-compile template.json --variables vars.json\r\n```\r\n\r\n## Schema Management\r\n\r\nWhen templates reference external schemas, you may be prompted to allow them:\r\n\r\n```\r\nSCHEMA ALLOWLIST DECISION REQUIRED\r\nURL: https://example.com/schema.json\r\n\r\n1. Allow permanently (saved to allowlist)\r\n2. Allow for this session only\r\n3. Deny (compilation will fail)\r\n```\r\n\r\n### Allowlist Commands\r\n\r\n```bash\r\n# Check current allowlist status\r\nits-compile --allowlist-status\r\n\r\n# Non-interactive mode (useful for CI/CD)\r\nits-compile template.json --no-interactive-allowlist\r\n```\r\n\r\n## Configuration\r\n\r\nSet environment variables to configure default behaviour:\r\n\r\n```bash\r\nexport ITS_INTERACTIVE_ALLOWLIST=false # Disable prompts\r\nexport ITS_REQUEST_TIMEOUT=60 # Increase timeout\r\nexport ITS_ALLOWLIST_FILE=/path/to/allowlist.json\r\n```\r\n\r\n## Error Examples\r\n\r\n### Missing Variable\r\n\r\n```\r\n\u2717 Variable Error: Undefined variable '${productName}'\r\n Available variables: topic, features\r\n```\r\n\r\n### Invalid Template\r\n\r\n```\r\n\u2717 Validation Error: Missing required field 'version'\r\n At: root\r\n```\r\n\r\n### Schema Issues\r\n\r\n```\r\n\u2717 Schema Error: Failed to load schema\r\n URL: https://example.com/schema.json\r\n```\r\n\r\n## Testing\r\n\r\nTest your CLI installation:\r\n\r\n```bash\r\n# Basic functionality test\r\necho '{\"version\":\"1.0.0\",\"content\":[{\"type\":\"text\",\"text\":\"Hello\"}]}' | its-compile /dev/stdin\r\n\r\n# Download test runner (optional)\r\ncurl -O https://raw.githubusercontent.com/AlexanderParker/its-compiler-cli-python/main/test_runner.py\r\npython test_runner.py\r\n```\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Make your changes and add tests\r\n4. Ensure all tests pass (`python test_runner.py`)\r\n5. Run linting (`black . && flake8`)\r\n6. Commit your changes\r\n7. Push to the branch and open a Pull Request\r\n\r\n### Development Setup\r\n\r\n```bash\r\n# Clone and setup\r\ngit clone https://github.com/AlexanderParker/its-compiler-cli-python.git\r\ncd its-compiler-cli-python\r\n\r\n# Create and activate virtual environment\r\npython -m venv venv\r\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\r\n\r\n# Install in development mode\r\npip install -e \".[dev]\"\r\n\r\n# Run tests\r\npython test_runner.py\r\n```\r\n\r\n### For Maintainers\r\n\r\n**Publishing to PyPI:**\r\n\r\nThis package is published to PyPI as `its-compiler-cli`. Releases are currently managed manually:\r\n\r\n```bash\r\n# Build the package\r\npython -m build\r\n\r\n# Test upload to TestPyPI first (recommended)\r\npython -m twine upload --repository testpypi dist/*\r\n\r\n# Upload to production PyPI (requires appropriate credentials)\r\npython -m twine upload dist/*\r\n```\r\n\r\n**TestPyPI Testing:**\r\n\r\n```bash\r\n# Install from TestPyPI to verify the package\r\npip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ its-compiler-cli\r\n```\r\n\r\n## Related Projects\r\n\r\n- **[ITS Compiler Python](https://github.com/alexanderparker/its-compiler-python)** - Core library\r\n- **[Instruction Template Specification](https://alexanderparker.github.io/instruction-template-specification/)** - Official specification\r\n- **[ITS Example Templates](https://github.com/AlexanderParker/its-example-templates)** - Example templates\r\n\r\n## License\r\n\r\nMIT License - see the [LICENSE](LICENSE) file for details.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Command-line interface for ITS Compiler - converts ITS templates to AI prompts",
"version": "1.0.4",
"project_urls": {
"Bug Tracker": "https://github.com/alexanderparker/its-compiler-cli-python/issues",
"Core Library": "https://github.com/alexanderparker/its-compiler-python",
"Homepage": "https://github.com/alexanderparker/its-compiler-cli-python",
"Repository": "https://github.com/alexanderparker/its-compiler-cli-python.git"
},
"split_keywords": [
"its",
" instruction",
" template",
" specification",
" ai",
" prompt",
" cli",
" command-line",
" compilation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4177daf0e2a5af5a440c90d7553410810af047a875c43d095b76d69364d606e5",
"md5": "ac47788fb838f1eebeb8dd6cf8f8cb54",
"sha256": "fbe62e5313fef96295916497f93cea5eb70a6d441a378fd2db512497e00045e5"
},
"downloads": -1,
"filename": "its_compiler_cli-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ac47788fb838f1eebeb8dd6cf8f8cb54",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13216,
"upload_time": "2025-07-21T17:36:43",
"upload_time_iso_8601": "2025-07-21T17:36:43.568516Z",
"url": "https://files.pythonhosted.org/packages/41/77/daf0e2a5af5a440c90d7553410810af047a875c43d095b76d69364d606e5/its_compiler_cli-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b7c5a3c2d60c0112baa42c0ed420d002b0984c7f03c42d1e3887ea1f3da81100",
"md5": "8ed5194a140e29a5927f4beb8f77b4b4",
"sha256": "0bf45368a2793f282a576e51920ab51dd5f903257880bcb387083765c32f5fda"
},
"downloads": -1,
"filename": "its_compiler_cli-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "8ed5194a140e29a5927f4beb8f77b4b4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 16069,
"upload_time": "2025-07-21T17:36:44",
"upload_time_iso_8601": "2025-07-21T17:36:44.550905Z",
"url": "https://files.pythonhosted.org/packages/b7/c5/a3c2d60c0112baa42c0ed420d002b0984c7f03c42d1e3887ea1f3da81100/its_compiler_cli-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 17:36:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexanderparker",
"github_project": "its-compiler-cli-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "its-compiler-cli"
}