# ct CLI One native binary. It generates twins, runs firmware, scenes and suites, and serves boards to your debugger, on your own machine. ## Install > **Getting ct** > > On macOS (13 or later, Apple silicon or Intel) and Linux (x86\_64 or ARM64), the command below installs a signed build and checks its SHA-256 first. The macOS build leaves out the commands for real boards (`ct hw`). On Windows, email [support@circuittwin.ai](mailto:support@circuittwin.ai) and we send you the package: `ct.exe` and `install.ps1`. 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](https://circuittwin.ai/docs/tokens), 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 | 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 | 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 | Run one firmware ELF on a board until a stop target, a budget or a fault. | | ct test run | 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 | 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 | 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 | 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 | Compile a ct.world/1 world into the scene a Proving Ground session runs, and explain every problem. | | ct world check | 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 | 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 | Serve a board over the GDB remote protocol for STM32CubeIDE, VS Code or plain gdb. | | ct gdb-bridge --session | Expose a debug session running on the hosted service on a local GDB port. | | ct ide setup \[vscode \| cubeide \| all\] --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 | 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 [--with ...] [--part ] [--force] [--output ] [--svd-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=]@[:]`. - `--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:`: fill memory the vendor documents as undefined with reproducible values. - `--display-png `: 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. |