cist-kernel 0.0.1

CLI for cist kernel telemetry and compilation

CIST Monorepo

Polyglot monorepo for the Contract Instruction Set (.cis) language.

This repository ships three user-facing pieces together:

• cist Python CLI for workspace bootstrapping, local syntax validation, and cloud compilation.
• A VS Code extension that adds .cis language registration, indentation rules, and syntax highlighting.
• A build orchestrator that packages the Python wheel and VSIX from one command.

What You Install

If you only want to write and validate .cis files locally, install the Python CLI.

If you want editor syntax highlighting for .cis, install the VS Code extension.

If you want to send contracts to the remote compiler, you need the CLI plus a CIST_CLOUD_API_KEY.

Language Snapshot

use math
use compute
use risk

market_data := from data (source: "binance", symbols: ["BTC-USD"], resolution: "1m")

sma_20 := math.sma(market_data.close, 20)
signal := compute.crossover(market_data.price, sma_20)

if signal and position.size == 0:
	execute(market_buy(size: risk.calculate_size(portfolio_value: 10000)))
elif position.pnl < -100:
	execute(close_position())

Repository Layout

cist/
├── pyproject.toml
├── README.md
├── .env.example
├── scripts/
│   └── build.py
├── cist_cli/
│   ├── __init__.py
│   ├── main.py
│   ├── parser.py
│   ├── network.py
│   └── assets/
│       └── .gitkeep
├── tests/
│   └── test_parser.py
└── vscode-extension/
	├── README.md
	├── package.json
	├── language-configuration.json
	└── syntaxes/
		└── cis.tmLanguage.json

Installation

Install From Source

Use this when you are developing CIST itself or want the latest local version.

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
cp .env.example .env

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
Copy-Item .env.example .env

Install The Built CLI Wheel

If a wheel has already been built, install it directly:

python -m pip install dist/cist-<version>-py3-none-any.whl

Install The VS Code Extension

Build the repo once, then install the generated VSIX from VS Code.

python scripts/build.py

That produces:

• dist/cist-<version>-py3-none-any.whl
• cist_cli/assets/cist-<version>.vsix

In VS Code, open Extensions, choose ..., then Install from VSIX... and select the file in cist_cli/assets/.

If you have the code shell command available, you can also run:

code --install-extension cist_cli/assets/cist-<version>.vsix

Quick Start

After installation, create a workspace and compile a sample contract:

cist init --path /tmp/test
cist validate /tmp/test/contracts/example.cis

CIST_CLOUD_API_KEY=sk_live_your_api_key_here cist compile /tmp/test/contracts/example.cis --verbose

The validate command is local-only. The compile command contacts the configured cloud endpoint.

How To Use CIST

Typical workflow:

1. Initialize a folder with cist init --path <dir>.
2. Edit the generated .cis file or add your own contracts under contracts/.
3. Run cist validate path/to/file.cis to catch local syntax issues before upload.
4. Run cist compile path/to/file.cis to stream compile output from the cloud service.
5. Add --deploy when you want the cloud request to mark the compile as deployable/live.

Example contract:

use math
use compute
use risk

market_data := from data (source: "binance", symbols: ["BTC-USD"], resolution: "1m")

sma_20 := math.sma(market_data.close, 20)
signal := compute.crossover(market_data.price, sma_20)

if signal and position.size == 0:
	execute(market_buy(size: risk.calculate_size(portfolio_value: 10000)))
elif position.pnl < -100:
	execute(close_position())

CLI Commands

cist init --path <dir>

• Creates a contracts/ directory.
• Writes an example.cis starter contract if one does not already exist.

cist validate <file.cis>

• Checks UTF-8 decoding.
• Checks bracket and quote matching.
• Collects use imports and from data (...) occurrences.
• Reports mixed tabs/spaces as warnings.

cist compile <file.cis> [--verbose] [--deploy]

• Runs the same local validation first.
• Sends the contract to the configured cloud endpoint.
• Streams logs, artifacts, and errors back to the terminal.

Configuration

The CLI reads environment variables directly and also loads them from .env if present.

Required for cloud compilation:

CIST_CLOUD_API_KEY=sk_live_your_api_key_here

Optional override:

CIST_CLOUD_ENDPOINT=https://api.cist.io/v1

Build Artifacts

Build both deliverables with:

python scripts/build.py

Expected outputs:

• dist/cist-*.whl
• cist_cli/assets/cist-*.vsix

Notes

• Local validation is lightweight and non-executing. It checks UTF-8 decoding, bracket matching, quote closure, use statements, from data (...) expressions, and mixed tab/space indentation.
• Cloud compilation requires CIST_CLOUD_API_KEY. The CLI also reads .env automatically if present.
• The VS Code grammar uses Python-style scope categories while adding CIST-specific handling for use and from data.