ct CLI

One native binary. It generates twins, runs firmware, scenes and suites, and serves boards to your debugger, on your own machine.

Install

macOS and Linux

curl -fsSL https://circuittwindownloads.blob.core.windows.net/cli/install.sh | sh
ct --version

Windows (PowerShell)

.install.ps1    # in the folder you unpacked
ct --version

Sign in

Every command except ct login needs a signed-in CircuitTwin account, and checks that the sign-in is still accepted, so a revoked token stops local commands too. --help works without one. Create an access token, then:

terminal

ct login --server https://app.circuittwin.ai          # prompts for the token
ct login --server https://app.circuittwin.ai --token-stdin < token.txt
ct login --status                                     # show and verify the stored sign-in

In CI, set CT_SERVER and CT_TOKEN instead. CT_TOKEN is only ever sent to the server CT_SERVER names.

Global options

--json: machine-readable JSON on stdout. Progress and problems go to stderr.
--help on any command or subcommand prints its full options.

Commands

Twins and parts

Command	What it does
`ct twin generate <DATASHEET>`	Generate a twin from a datasheet PDF, or an SVD file for an SVD-only MCU import. Reuses the catalog entry when the part already exists.
`ct twin from-bom`	Build twins from bill-of-materials lines without a datasheet; the twin carries its part class defaults.
`ct catalog find <TEXT>`	Find components by part number, alias or text.
`ct pack resolve \| import \| find \| list`	Resolve a part to its CMSIS pack and cache it, add a local .pack, or list the cache.
`ct board import`	Import a printed circuit board design as a board document.

Run and test

Command	What it does
`ct run --board <BOARD> <FIRMWARE>`	Run one firmware ELF on a board until a stop target, a budget or a fault.
`ct test run <SUITE>`	Run a test suite locally, in parallel, with JUnit and JSON reports and baseline comparison.
`ct scenario list \| check \| simulate \| view`	List, validate, simulate and draw telemetry scenarios.
`ct scene run <SCENE>`	Run a ct.scene/1 file: several boards on UART, SPI and I2C links, CAN and RS-485 buses and Ethernet, in lock-step virtual time. --cloud runs it on the hosted service.
`ct scene rerun <ID>`	Run a scene run of the hosted service again with the same inputs, such as a Proving Ground session saved as a test.
`ct system compile <SYSTEM>`	Compile a ct.system/2 document (or an older ct.system/1 or a board) into the scene it describes, and explain every wire problem.
`ct system convert \| digest`	Write a board or a ct.system/1 document as ct.system/2; print a system’s id and content digest.
`ct capture decode \| import \| replay \| survey`	Decode sigrok captures of real buses and replay them against a twin.

Worlds and 3D models

Command	What it does
`ct world compile <WORLD>`	Compile a ct.world/1 world into the scene a Proving Ground session runs, and explain every problem.
`ct world check <WORLD>`	List what is missing before the world runs: the same list as the Check tab. Exits 1 when something blocks the run.
`ct asset import <FILE>`	Import a 3D model (GLB, glTF, STL, OBJ, STEP or a KiCad PCB) with its size, collision shape and material.
`ct assembly import \| world \| simulate`	Import a URDF, SDF, MJCF or FreeCAD assembly, add its parts and joints to a world, and run its mechanism.

Debug and IDE

Command	What it does
`ct gdb-server --board <BOARD>`	Serve a board over the GDB remote protocol for STM32CubeIDE, VS Code or plain gdb.
`ct gdb-bridge --session <ID>`	Expose a debug session running on the hosted service on a local GDB port.
`ct ide setup [vscode \| cubeide \| all] --elf <ELF>`	Write debug configurations so the IDE flashes, debugs and runs on CircuitTwin.

Hardware comparison

Command	What it does
`ct hw detect \| flash \| run \| dump \| parity`	Run the same image on a connected board and on its twin and compare the transcripts (NUCLEO-F767ZI over ST-LINK by default).
`ct hw scan`	Identify the chip on a connected board read-only, find the parts on its I2C bus and write the twin that reproduces it.
`ct hw --target esp \| esp32 \| rp \| teensy \| unoq ...`	The same tools for Espressif, Raspberry Pi Pico 2, Teensy 4.1 and Arduino UNO Q boards.

Account and hosted service

Command	What it does
`ct login --server <URL>`	Store an access token for a server (read from a prompt or --token-stdin, never the command line). --status checks it, --logout forgets it.
`ct cloud ...`	Scripted access to the hosted API: whoami, catalog, source, twin, mcu, firmware, project, board, run, suite, job, session and api.
`ct sample seed`	Fill a workspace with a curated sample pack: sensor twins, an MCU, firmware, boards, runs and suites.

ct twin generate

terminal

ct twin generate <DATASHEET> [--with <COMPANIONS>...] [--part <PART>] [--force] [--output <PATH>] [--svd-dir <DIR>]

--with: companion documents (reference manual, errata, vendor headers).
--part: the part number when the datasheet covers several parts.
--output: also write the twin bundle and its facts to a .json file or a directory.
--force: regenerate even if the catalog already has the part.

ct run

terminal

ct run --board nucleo-f767zi build/app.elf \
  --device INA226@I2C1:0x40 \
  --scenario bench-warmup.yaml \
  --uart-input "USART3@100=status\n" \
  --until "READY" --max-ms 5000

--board: a board file or built-in board id (nucleo-f767zi, stm32f4-discovery, nucleo-f103rb, or a derived board such as feather-nrf52832; an unknown id lists them all).
--device: add a part on a bus, [name=]<twin>@<bus>[:<address|cs-pin>].
--until: console text, symbol:NAME or pc:0xADDR. --max-ms is the virtual time budget (default 10000).
--scenario: a telemetry scenario file or bundled scenario id.
--timing cycle-approximate: the opt-in timing layer. It is provisional, and a part without a timing profile is refused.
--uninitialized-memory seeded:<seed>: fill memory the vendor documents as undefined with reproducible values.
--display-png <DIR>: write each display controller’s frame memory as a PNG.

ct test run

terminal

ct test run suite.yaml --junit out/junit.xml --report out/ \
  --baseline main-report.json --fail-on-regression

Filter cases with --filter TEXT or --tag TAG, list them without running with --list, and set parallelism with --workers.

Exit codes

Code	ct run	ct test run
`0`	The run reached its target, or ended within its budget without a fault	Every selected case passed (and no regression with --fail-on-regression)
`1`	Target never reached, fault or lockup	A case failed or errored, or a regression was found
`2`	Invalid input: unknown board, missing twin, firmware that does not fit the MCU	Invalid suite, nothing selected, unreadable baseline
`3`	Platform error	Platform error (outputs could not be written)
`4`	Inconclusive: completed, but on peripherals the twin does not model	Not used

Environment

Variable	Meaning
`CT_SERVER`, `CT_TOKEN`	Sign in without ct login (CI). The token is only sent to that server.
`CT_CONFIG_DIR`	Where ct login keeps its credentials file (default: your user profile’s config directory).
`CT_SVD_DIR`	CMSIS-SVD files for MCU imports and ct ide setup.
`CT_PACK_CACHE`	The CMSIS pack cache (default: a per-user cache).
`CT_ARM_GDB`	The arm-none-eabi-gdb that ct ide setup writes for VS Code.