4.8 Command line

The IDE also works in a terminal, without a window. validate checks a project and ends. run validates a project, runs it with its bridges in the IDE's Docker container and prints what happens until it is stopped.

4.8.1 Commands#

Usage:
  karpfen-ide [<folder>]
  karpfen-ide validate <folder> [--format text|json]
  karpfen-ide run <folder> [--descriptor <file>] [--bridge <file>]... [--capture] [--verbose]
CommandEffect
karpfen-ide <folder>Opens the window on the folder. Without a folder the window opens on its welcome view.
karpfen-ide validate <folder>Validates the whole project, prints the findings and ends.
karpfen-ide run <folder>Validates the project, runs it and prints what happens until it is stopped.
karpfen-ide validate --help, karpfen-ide run --helpPrints the usage and ends with status 0. -h does the same.

Options may stand before or after the folder. A value follows its option as the next argument or after =, as in --bridge=http.kbridge.json. -- ends the options, so a folder after it may start with -. A folder that is itself named validate or run must be written with a path in front, as in ./run, when it is the first argument.

A wrong command line prints karpfen-ide: and what is wrong, then the usage, on the error output, and ends with status 2. Wrong are an unknown option, a missing, second or empty folder, a folder that does not exist, an option without its value, a second --descriptor or --format, a format other than text or json, a bridge named twice, and an option that the command does not take.

karpfen-ide: unknown option '--frmat'

4.8.2 Starting it#

FromCommand
The sources./gradlew :app:ide:run --args="validate /absolute/path/to/project"
The application on macOSkarpfen-ide.app/Contents/MacOS/karpfen-ide validate <folder>
The application on Linuxkarpfen-ide/bin/karpfen-ide validate <folder>
The application on Windowskarpfen-ide\karpfen-ide.exe validate <folder>

From the sources the folder must be an absolute path. ./gradlew :app:ide:createDistributable builds the application into app/ide/build/compose/binaries/main/app/. On Windows the application is built with a console, so the commands have somewhere to print, and opening the window by a double-click also opens a console window.

4.8.3 Validating#

karpfen-ide validate examples/lamp

The command runs the same checks as Validate in the window, see 4.4 Validating. It prints one line per finding, errors first, and then a summary. A project without findings prints No problems found.

lamp.kstates:13: error: mismatched input 'STATMACHINE' expecting 'STATEMACHINE'
switch.kstates:8: warning: This EVAL has no return, so it yields no value; return the value it computes
1 error and 1 warning

The language features are those of the .karpfenproject file of the folder, see 4.1.7 Language features. karpfen-ide validate examples/spares checks the example with attachable state machines, whose project file switches on macros. A finding about a behaves after is printed at the line of the metamodel, as in spares.kmeta:4: error: ....

With --format json it prints one JSON document instead, for a program to read.

karpfen-ide validate examples/lamp --format json
{
    "root": "/home/me/karpfen-IDE/examples/lamp",
    "errorCount": 1,
    "warningCount": 1,
    "problems": [
        {
            "path": "lamp.kstates",
            "line": 13,
            "column": 1,
            "severity": "error",
            "message": "mismatched input 'STATMACHINE' expecting 'STATEMACHINE'",
            "code": "syntax-error"
        },
        {
            "path": "switch.kstates",
            "line": 8,
            "column": 33,
            "severity": "warning",
            "message": "This EVAL has no return, so it yields no value; return the value it computes",
            "code": "kstates.eval-without-return"
        }
    ]
}
MemberMeaning
rootThe folder of the project, as an absolute path.
errorCount, warningCountHow many errors and warnings the project has.
problemsThe findings, sorted by path, line and column.
pathThe file, relative to the folder.
line, columnWhere the finding starts. Both count from 1.
severityerror, warning, info or hint.
messageWhat is wrong, in words.
codeThe stable name of the kind of finding.

4.8.4 Running#

karpfen-ide run examples/lamp --descriptor lamp.kenv.json --bridge http.kbridge.json --capture
OptionMeaning
--descriptor <file>The descriptor to run, relative to the folder or absolute. It can be left out when the project has exactly one.
--bridge <file>A bridge file of the project to start with the run. Give the option once per bridge. Without it no bridge starts.
--captureWrites the log of the run to a file in karpfen-runs/, as Capture run to file does in the window, see 4.5.8 Captured logs.
--verboseAlso prints every line of the runtime's log.

The choice of files is checked against the project, and a wrong choice ends with status 2, a message and the usage.

CaseMessage
The project has no descriptor.the project has no environment descriptor (*.kenv.json)
The project has several descriptors, and --descriptor is missing.the project has several environment descriptors; choose one with --descriptor: and the list
--descriptor names no descriptor of the project.<file> is no environment descriptor of the project; and the list
--bridge names no bridge file of the project.<file> is no bridge file of the project; and the list

A run goes through these steps.

  1. It validates the whole project. With an error it prints the findings as validate does and does not run. With warnings only it prints them the same way, then The run goes on despite the warnings., and runs.
  2. It starts the runtime in the IDE's Docker container. The first run builds the runtime image.
  3. It deploys the descriptor and starts the bridges.
  4. It prints what happens until you stop it with Ctrl+C or a terminate signal.
  5. It stops the bridges and the environment, removes the runtime container and ends.

Stopping the environment in step 5 also drops it, so the runtime forgets it before the container goes. A run whose environment another client stops or drops ends with The run ended on its own., as 4.5.5 Stopping a run describes.

This is what a run of the lamp with one bridge prints. The switch is pressed once through the bridge, and then the run is stopped. The first run prints a line for each step of building the image as well.

Running lamp.kenv.json with http.kbridge.json
Docker: not started
Run lamp: preparing
Run lamp: waiting for the runtime
Docker: checking the Docker engine
Docker: creating the container
Docker: starting the container
Docker: waiting for the runtime
Docker: running at 127.0.0.1:65457
Run lamp: deploying
http.kbridge.json: not running
Checking the runtime at http://127.0.0.1:65457: done, The runtime is up and supports the IDE
Creating the environment: done, env-1794579423685
Connecting to the environment: done, Connected as karpfen-ide-254666e10161
Uploading lamp.kmeta: done
Uploading lamp-events.kmeta: done
Uploading lamp.kmodel: done
Attaching lamp.kstates to lamp: done
Attaching switch.kstates to wallSwitch: done
Setting the tick delay to 500 ms: done
Setting the event time to live to 5000 ms: done
Listening to 2 event domains: done, service, switch
Switching on runtime features: skipped, The project switches on no language feature that needs one
Activating the environment: done
Switching observation on: done, The runtime read the model as analyzed
Starting the environment: done
14:17:03.888  lamp  starts in off
14:17:03.890  wallSwitch  starts in down
14:17:03.892  engine  Engine started with 2 state machine(s), tickDelay=500ms
14:17:03.895  lamp  runs the entry actions of off
lamp: off
wallSwitch: down
Confirming the start: done, Every state machine reported its state
Run lamp: running
http.kbridge.json: starting
http.kbridge.json: running, 0 in, 0 out
14:17:04.896  lamp  off -> full
14:17:04.898  wallSwitch  down -> up
lamp: on > full
wallSwitch: up
14:17:05.397  lamp  runs the entry actions of on
14:17:05.399  lamp  runs the entry actions of full
14:17:05.414  wallSwitch  runs the entry actions of up
Stop requested.
Shutting down the run and its bridges, then the runtime.
Run lamp: stopped
http.kbridge.json: not running
14:17:06.405  engine  Engine stopped after 5 ticks
Docker: not started
Shut down.
LineMeaning
Running <descriptor> with <bridges>What the run was asked to do. , captured to a file is added with --capture, and , parallel branches on threads of their own while the project has Parallel branches on threads switched on, see 4.1.7 Language features.
Docker: ...What the runtime container does, in the words of the Runtime tool window.
Run <name>: <phase>The phase of the run, as in 4.5.4.2 The runs.
<step>: done, skipped or failed, with a detailA step of the deployment.
<object>: <states>, <object> (<definition>): <states>The active states of the state machine instance on that object, whenever the runtime reports new ones. An instance of a definition also names its definition. An instance that ends and a later one on the same object are two instances, so the first states of the later one are printed too.
<bridge file>: ...The state of a bridge, and once it runs how many messages it took in and sent out.
<time> <object> <text>A line of the simplified log, as the Log pane shows it.
<severity>: <file>:<line>:<column>: <message>A problem of the preparation or the run.
[stdout] ..., [stderr] ...A line of the runtime's log, with --verbose.
Captured to karpfen-runs/<file>Where the run is captured.
Stop requested., Shutting down ..., Shut down.The end of the run. What the bridges and the runtime say while they stop stands in between.

A descriptor with definitions uploads each of them in a step Uploading the definition <file>. The objects get and lose instances of the definitions while the run goes on, and the simplified log says so in lines such as bulb attaches glowing, bulb exchanges glowing for flickering and bulb detaches flickering, see 4.5.4.7 State machine instances. This is part of what a run of examples/spares prints when the event flicker comes in:

bulb (glowing): lit
spare (glowing): lit
14:20:16.500  bulb  exchanges glowing for flickering
14:20:16.501  bulb  starts in on
bulb (flickering): on

A descriptor with fragments uploads each of them in a step Uploading the fragment <file>. The states of a fragment carry the name of their container state in front, so a run of examples/pages prints lines such as lamp: self test > self test/wiring > self test/wiring/measuring, see 4.5.4.8 Pages.

A run that does not get going says why and ends with one of these lines.

LineStatus
The run does not start: the project has errors.1
The run did not start.3
The run does not start: the deployment is blocked.3
The run failed.3
The run ended on its own.3

4.8.5 What a run reads from the project#

A run without a window takes one thing from .karpfenproject: which features are on, the optional language features and the features of the project such as Parallel branches on threads. Everything else in that file, such as the bridges ticked in the window, is ignored. Nothing is written, neither to .karpfenproject nor to the settings of the user. A run without a window has no debugger, so breakpoints never halt it, also when the project has them switched on. It has no time limit and ends only when it is stopped.

4.8.6 Exit statuses#

StatusMeaning
0The validation found no error. Warnings are allowed. Also after --help.
1The project has errors. A run did not start.
2The command line was wrong. A message and the usage are printed.
3A run could not start, failed or ended on its own, or the folder could not be opened as a project.

A run that is stopped by a signal ends with the status the system gives a process that got that signal. A run started through Gradle therefore makes the Gradle task fail when it is stopped.

Source: this page on GitHub at commit 3b6029f, refreshed 16 November 2026. The whole reference as a PDF.