cist-kernel 0.0.8

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-kernel Python package — the CLI, the syntax validator, and the cloud compiler client.
• A VS Code extension bundled inside the package — sync it explicitly with cist sync-vscode-extension.
• A build orchestrator (scripts/build.py) for cutting releases.

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

Getting Started

python -m pip install --upgrade cist-kernel
python -m cist_cli

Works on Windows, macOS, and Linux immediately after install — no PATH setup, no extra tools. Running python -m cist_cli with no arguments automatically runs init.

If you installed an older release already, the --upgrade matters. Plain pip install cist-kernel will keep the old version and will not add the newer python -m cist_cli entrypoint.

After init runs, if cist isn't yet on your PATH it will print the exact one-liner to fix it permanently. Once you've done that (and reopened your terminal), you can use the short form for everything:

cist compile contracts/my_strategy.cis

init creates a workspace and writes a .env config file. To install or refresh the bundled VS Code syntax extension, run python -m cist_cli sync-vscode-extension, or cist sync-vscode-extension after PATH is configured.

Add --deploy to mark a build as live:

cist compile contracts/my_strategy.cis --deploy

How To Use CIST

1. python -m pip install --upgrade cist-kernel — install the latest release.
2. python -m cist_cli — first run (works before PATH is configured). No args = auto-runs init. After this, use cist init / cist compile directly.
3. Add your CIST_CLOUD_API_KEY to the generated .env.
4. Write .cis files in contracts/.
5. cist compile <file.cis> — validates syntax locally, then streams compilation output from the cloud.

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 Reference

cist init [--path <dir>]

• Creates contracts/ and example.cis.
• Writes a .env stub with CIST_CLOUD_API_KEY placeholder.
• Leaves VS Code untouched by default.
• Use --install-vscode-extension if you want one-shot setup plus extension install.

cist sync-vscode-extension

• Installs or updates the bundled .cis VS Code extension.
• Uses the latest bundled VSIX from cist_cli/assets/.
• Fails with a clear message if VS Code is not installed or the bundled VSIX is missing.

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

• Validates syntax locally first (bracket matching, use imports, from data expressions, encoding).
• Streams compilation logs, artifacts, and errors from the cloud compiler.
• --deploy flags the build as ready for live execution.
• --verbose prints detected modules and data stream count.

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.