cist-kernel 0.0.2

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 — installed automatically by cist init.
• 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

pipx install cist-kernel
cist init

pipx handles PATH automatically on Windows, macOS, and Linux — no terminal restarts, no admin rights needed. If you don't have pipx yet: pip install pipx.

init creates a workspace, writes a .env config file, and — if VS Code is detected — installs the .cis syntax extension automatically. Open contracts/example.cis and start writing.

When you're ready to send a contract to the cloud compiler:

cist compile contracts/my_strategy.cis

Add --deploy to mark the build as live:

cist compile contracts/my_strategy.cis --deploy

How To Use CIST

1. pipx install cist-kernel — one-time install.
2. cist init — creates a contracts/ folder, a .env config stub, and installs the VS Code extension if detected.
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.
• Detects VS Code and installs the bundled .cis extension automatically.

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.