cist-kernel 0.0.18

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 — cist init installs it into your local VS Code extensions folder.
• 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
cist init

If cist is not on your PATH yet, use the fallback:

python -m cist_cli

Works on Windows, macOS, and Linux immediately after install — 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, writes a .env config file, removes the broken legacy CIST extension if present, and installs the bundled VS Code syntax extension. If you want to re-run only the extension step later, use 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. cist init — preferred first run. If cist is not on PATH yet, use python -m cist_cli instead. No args = auto-runs init.
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.
• Removes the broken legacy tooig research lab.cist extension if it exists.
• Installs the bundled .cis VS Code extension into your local extensions folder.

cist sync-vscode-extension

• Re-installs or updates the bundled .cis VS Code extension.
• Uses the latest bundled VSIX from cist_cli/assets/.
• Fails with a clear message if the bundled VSIX is missing or the extensions folder cannot be written.

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_kernel-*.whl

During the build, a .vsix is created temporarily so it can be bundled into the wheel. The local build script removes that generated .vsix afterward, so it does not stay in the repo.

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.