FAQs & Tutorials / Tutorial
Tutorial · Automation

Controlling Incisor® from the command line.

Publish a project, open it, take a screenshot, or run a script in the inspector, all from a terminal, a build script, or an AI agent. Each command gets one JSON answer and an exit code, so anything that can run a program can drive Incisor®.

TutorialCLIAutomationPublishingAPISettings11 min read

The short version

Incisor® accepts one command at a time from the command line, whether it's open or closed. You run the Incisor® executable with --cli and one JSON object. It waits until the command is done, prints one JSON answer on stdout, and exits with a code.

The command line isn't part of the Incisor® API documentation, so this page is the full reference for it. There are seven commands:

CommandDoesWorks with Incisor® closedDefault timeout
getSessionInfoReturns the application settings and the open projects.Yes15 s
publishPublishes a project with a named configuration.Yes1800 s
openProjectOpens a project in a tab.Yes, and Incisor® stays open60 s
focusTabBrings a project's tab and the window forward.No10 s
getInspectorScreenShotSaves an image of a project's whole tab.No30 s
getProjectScreenShotSaves an image of a running project.No30 s
runNceScriptRuns a script inside an open project's inspector.No30 s
A Mac terminal running the publish command, followed by the JSON answer with ok true and the publish summary
A publish command on a Mac and its answer, filtered with jq. ok is true, and result holds the publish summary.

Before you start

Incisor® 2026.11.05.00.00.00 or later

The command line isn't available in earlier versions. Use Incisor® menu → Check for Updates to update.

A logged-in user

publish and openProject need a verified user, so Incisor® must have been logged in and its key must still be valid.

Know the risk. Once the command line is on, any program on your computer, including programs run by other user accounts, can issue these commands. A script can do anything the open project can do. Turn it on only on a machine you trust.

1 · Turn on the command line

The command line is off by default. It's controlled by one application setting, enableCLI, in the security group.

  1. Open Incisor® menu → Application Settings...
  2. In the security group, turn on enableCLI.
    Application Settings with enableCLI checked in the security group
    enableCLI is in the security group, below allowEditorDebugging.
  3. Confirm the prompt, which reads: "By enabling this feature, you agree to assume responsibility for all of the associated risks. Do you wish to continue?"
    Verification prompt: By enabling this feature, you agree to assume responsibility for all of the associated risks. Do you wish to continue?

The setting takes effect immediately, with no restart. Every command is recorded in the Incisor® log and in the shell log when it's received, whether or not it's then allowed to run.

2 · Run a command

Run the Incisor® executable with one of these flags:

FlagDoes
--cli <json>Runs the command given as one JSON object.
--cli-file <path>Runs the command held in a file. Best for long scripts, and on Windows.
--output <path>Also writes the answer to a file.

The JSON object always has a command name, plus that command's arguments. Any command can also take timeoutSeconds.

Running a command on a Mac

The default location is /Applications/Incisor.app/Contents/MacOS/Incisor. Incisor® can be dragged anywhere, so if yours isn't in Applications, use the same path inside your own copy of Incisor.app. Run this executable directly, because open starts a second app instead.

Mac terminal
/Applications/Incisor.app/Contents/MacOS/Incisor --cli '{"command":"getSessionInfo"}'

Running a command on Windows

The default location is %LOCALAPPDATA%\Programs\Incisor\Crimson\Incisor.exe. The Crimson folder is named after the version set. The installer also lets you pick another folder. If you did, right-click the Incisor® Crimson Start Menu shortcut and choose Open file location.

Put the command in a file and read the answer from --output, since a desktop program's stdout isn't shown by every terminal.

command.json
{ "command": "getSessionInfo" }
Windows cmd
"%LOCALAPPDATA%\Programs\Incisor\Crimson\Incisor.exe" --cli-file command.json --output answer.json
Windows PowerShell
& "$env:LOCALAPPDATA\Programs\Incisor\Crimson\Incisor.exe" --cli-file command.json --output answer.json

Backslashes in a JSON file must be doubled, as in "C:\\Users\\you\\Desktop\\MyProject".

Project paths

projectPath is the folder of the project. Relative projectPath and outputPath values work, and are taken from the folder the command was issued in.

A ~ inside single quotes isn't expanded by the shell, so build a home-based path from $HOME instead. The quotes close around "$HOME" and then reopen:

Mac terminal
/Applications/Incisor.app/Contents/MacOS/Incisor --cli '{"command":"publish","projectPath":"'"$HOME"'/Desktop/MyProject","configName":"LocalDev"}'

3 · Read the answer

Every command answers with one JSON object. The answer is only what's on stdout or in the --output file. Ignore stderr, which carries a DevTools listening on ws://127.0.0.1:<port>/... line whenever the editor debugging port is on.

FieldHolds
docFormatVersionThe version of this answer format, currently 1.
oktrue if the command worked, false if it failed.
commandThe name of the command.
resultWhat the command returned. Only present when ok is true.
errorAn object with code and message. Only present when ok is false.
logsLines logged while the command ran. These can include lines from other activity.
A command that worked
{ "docFormatVersion": 1, "ok": true, "command": "focusTab", "result": { "focused": true }, "logs": [ "..." ] }
A command that failed
{ "docFormatVersion": 1, "ok": false, "command": "focusTab", "error": { "code": "notOpen", "message": "The project is not open: /Users/you/Desktop/MyProject" }, "logs": [ "..." ] }

Check error, not just result. On a failure, error replaces result, so a filter such as jq '{ok, command, result}' hides the reason. Include error in the filter.

A good everyday pattern on a Mac drops stderr and keeps the fields that matter:

Mac terminal
/Applications/Incisor.app/Contents/MacOS/Incisor --cli '{"command":"focusTab","projectPath":"'"$HOME"'/Desktop/MyProject"}' 2>/dev/null | jq '{ok, command, result, error}'

An --output file is written whole, so a script never reads half of an answer.

Exit codes

CodeMeaningError codes
0The command worked.None
1The command failed.Every code not listed in the rows below, including timeout
2The command line is turned off.cliDisabled
3Incisor® gave no answer or wasn't ready.noResponse, unavailable, notReady

Error codes

When ok is false, error.code is one of these, and error.message gives the detail.

CodeExitMeaningWhat to do
cliDisabled2enableCLI is off.Turn it on in Application Settings.
badCommand1Invalid JSON, an unreadable command file, or no command name.Fix the JSON or the file path.
unknownCommand1The name isn't one of the seven commands.Check the spelling, which is case-sensitive.
missingArgument1A required argument is missing or empty.error.message names it.
notOpen1The project isn't open, or Incisor® is closed.Run openProject first.
notRunning1getProjectScreenShot was run on a project that's open but not running.Run the project, then try again.
alreadyOpen1openProject was run on an open project.Carry on, since the project is ready. Use focusTab to bring it forward.
notAProject1publish was given a path that isn't a valid project.Point projectPath at the project's folder.
notVerified1The user isn't verified.Open Incisor® and log in.
projectBusy1A publish of this project is underway, or assets were still processing when time ran out.Wait, then try again, with a longer timeoutSeconds if needed.
publishFailed1The publish reported an error.Read error.message.
openFailed1The project couldn't be opened.Read error.message.
scriptError1A runNceScript script failed.Read error.message and fix the script.
actionFailed1The window couldn't focus the tab or take the screenshot.Read error.message.
timeout1focusTab, getInspectorScreenShot, getProjectScreenShot or runNceScript ran out of time.It may still finish. Check before running it again.
noResponse3No answer arrived within timeoutSeconds plus 20 seconds.It may still finish. Check before running it again.
unavailable3Incisor® isn't running, or stopped before the command finished.Try again.
notReady3Incisor® didn't finish starting up within 120 seconds.Try again.
internalError1The command failed unexpectedly.Read error.message and logs.

Timeouts

Each command has its own time limit in seconds, shown in the table at the top of this page. Add timeoutSeconds to any command to change it:

command.json
{ "command": "runNceScript", "projectPath": "/Users/you/Desktop/MyProject", "script": "return 6 * 7;", "timeoutSeconds": 120 }

A command that times out may still finish in Incisor®. Before you run it again, check whether the work was done.

Commands

Every command that names a project takes projectPath, the folder of the project. All examples use /Users/you/Desktop/MyProject. In the longer answers, "..." marks what was cut.

getSessionInfo

Returns the application settings and the projects that are open.

DetailValue
ArgumentsNone
NeedsNothing. Works with Incisor® open or closed.
Default timeout15 seconds
ResultapplicationSettings and openProjects
Each open projectprojectPath, projectName, isRunning, projectSettings

This answer is long. It holds the full projectSettings of every open project, about 450 lines each, so filter it before putting it in a prompt. See Common workflows below for a filter.

Command
{ "command": "getSessionInfo" }
Answer (abbreviated)
{
  "docFormatVersion": 1,
  "ok": true,
  "command": "getSessionInfo",
  "result": {
    "applicationSettings": {
      "docFormatVersion": 0,
      "incisorVersion": "2026.11.04.11.13.35",
      "language": "en",
      "logs": { "verbosity": "high", "entryCharLimit": 500 },
      "maxUndoStates": 500,
      "connectionPorts": [8000, 8001, 8002, "..."],
      "colorTheme": "Default",
      "customColorThemes": [{ "name": "...", "colors": "..." }, "..."],
      "maxThreads": 8,
      "refreshOnCodeChange": true,
      "runProjectOnOpen": false,
      "stopProjectOnException": true,
      "security": {
        "allowUniversalFileIO": true,
        "allowExternalExecutableProcesses": true,
        "allowEditorDebugging": true,
        "editorDebuggingPort": 9222,
        "enableCLI": true,
        "allowRemoteHosting": false
      },
      "...": "..."
    },
    "openProjects": [
      {
        "projectPath": "/Users/you/Desktop/MyProject",
        "projectName": "MyProject",
        "isRunning": false,
        "projectSettings": {
          "publicProjectName": "MyProject",
          "projectCodeName": "MyProject",
          "latestIncisorVersionSetUsed": "Crimson",
          "latestIncisorVersionUsed": "2026.11.04.11.13.35",
          "usingTypescript": true,
          "devModeConfiguration": "LocalDev",
          "configurations": {
            "LocalDev": { "publishIndexFile": true, "...": "..." },
            "EgmSingleScreenPublish": "...",
            "EgmDualScreenPublish": "..."
          },
          "screenShotDestination": "ScreenShots",
          "...": "..."
        }
      }
    ]
  },
  "logs": [
    "74 CLI: Command line command received: {\"command\":\"getSessionInfo\",\"timeoutSeconds\":15}",
    "75 CLI: Command line command 'getSessionInfo' succeeded."
  ]
}

The names under configurations are the values publish accepts for configName.

publish

Publishes the project with the named configuration. It waits for any asset processing that's already underway.

DetailValue
ArgumentsprojectPath, configName
NeedsA verified user. Works with Incisor® open or closed, and with the project open or not.
Default timeout1800 seconds
Resultresult, hostedPort, publishTimeStamp, destinationDirectory
ErrorsmissingArgument, notVerified, notAProject, projectBusy, publishFailed, noResponse

In the result, hostedPort is -1 when nothing is hosted, and destinationDirectory is the folder holding the published build.

Command
{ "command": "publish", "projectPath": "/Users/you/Desktop/MyProject", "configName": "LocalDev" }
Answer (abbreviated)
{
  "docFormatVersion": 1,
  "ok": true,
  "command": "publish",
  "result": {
    "result": "project publishing complete.",
    "hostedPort": -1,
    "publishTimeStamp": "2026.11.04.11.51.42",
    "destinationDirectory": "/Users/you/Desktop/MyProject/Publishing/Builds/2026.11.04.11.51.42_LocalDev"
  },
  "logs": [
    "76 CLI: Command line command received: {\"command\":\"publish\",\"projectPath\":\"/Users/you/Desktop/MyProject\",\"configName\":\"LocalDev\",\"timeoutSeconds\":1800}",
    "...",
    "101 CLI: Command line command 'publish' succeeded."
  ]
}

If the project wasn't open, publish opens it without a tab, doesn't add it to your recent projects, and closes it again afterward.

publish skips two things. The prePublish and postPublish events that extensions listen for don't fire, because they belong to the inspector, and the published project isn't hosted. If you need the events, see Publishing with events below.

openProject

Opens the project in a tab, starting Incisor® if it's closed.

DetailValue
ArgumentsprojectPath
NeedsA verified user. The project must not already be open.
Default timeout60 seconds
ResultprojectPath, pageUrl
ErrorsmissingArgument, notVerified, alreadyOpen, openFailed, noResponse
Command
{ "command": "openProject", "projectPath": "/Users/you/Desktop/MyProject" }

focusTab

Brings the project's tab and the window forward.

DetailValue
ArgumentsprojectPath
NeedsIncisor® open, and the project open.
Default timeout10 seconds
Resultfocused, which is true
ErrorsmissingArgument, notOpen, actionFailed, timeout
Command
{ "command": "focusTab", "projectPath": "/Users/you/Desktop/MyProject" }

getInspectorScreenShot

Focuses the project's tab and saves an image of the whole tab as a PNG.

DetailValue
ArgumentsprojectPath, and optionally outputPath
NeedsIncisor® open, and the project open.
Default timeout30 seconds
Resultpath, width, height
ErrorsmissingArgument, notOpen, actionFailed, timeout

With no outputPath, the image goes in a temporary folder. Read path in the result to find it.

Command
{ "command": "getInspectorScreenShot", "projectPath": "/Users/you/Desktop/MyProject", "outputPath": "/Users/you/Desktop/inspector.png" }

getProjectScreenShot

Brings the project's tab and the window forward, then saves an image of the project's main render target as a PNG.

DetailValue
ArgumentsprojectPath, and optionally outputPath
NeedsIncisor® open, and the project open and running.
Default timeout30 seconds
Resultpath, which is absolute, plus width and height
ErrorsmissingArgument, notOpen, notRunning, actionFailed, scriptError, timeout

With no outputPath, the image goes to the folder set by screenShotDestination in Project Settings, which is ScreenShots in the example above. An outputPath outside the project's folders needs allowUniversalFileIO, since the project's own file rules apply.

Command
{ "command": "getProjectScreenShot", "projectPath": "/Users/you/Desktop/MyProject" }

runNceScript

Runs a script inside the open project's inspector, with nce available as it is in extensions. The script may use await, and may return a value.

DetailValue
ArgumentsprojectPath, script
NeedsIncisor® open, and the project open.
Default timeout30 seconds. Raise it for anything slow.
Resultvalue if the script returns a value. Otherwise result is empty.
ErrorsmissingArgument, notOpen, scriptError, timeout
  • nc and pr aren't available, the same as in extensions. Those two names are reserved, so a script can't declare variables called nc or pr either.
  • To reach the running project, use nce.projectNC (the project's nc) and nce.projectPR (the project's pr).
  • The script is limited by the same settings that limit extensions, such as allowUniversalFileIO and allowExternalExecutableProcesses.
  • Inside JSON, a script's double quotes must be written \" and its line breaks \n, so --cli-file is easier for long scripts.
Command
{ "command": "runNceScript", "projectPath": "/Users/you/Desktop/MyProject", "script": "return 6 * 7;" }
Answer
{ "docFormatVersion": 1, "ok": true, "command": "runNceScript", "result": { "value": 42 }, "logs": [ "..." ] }
Answer when the script returns nothing
{ "docFormatVersion": 1, "ok": true, "command": "runNceScript", "result": { }, "logs": [ "..." ] }

Publishing with events

To publish an open project and fire the prePublish and postPublish events, use runNceScript and trigger them around nce.publishing.publishProject, which is what the inspector does itself. Replace "Web" with the name of your configuration.

Script
const info = { configurationName: "Web", proceedWithPublishing: true, hostPublishedProject: false };
await nce.appEvents.prePublish.asyncTrigger(info);
let summary;
if(info.proceedWithPublishing)
{
    const response = await nce.publishing.publishProject(info.configurationName, info.hostPublishedProject);
    summary = response.payload;
    await nce.appEvents.postPublish.asyncTrigger({ configurationName: info.configurationName, publishTimeStamp: summary.publishTimeStamp, destinationDirectory: summary.destinationDirectory, hostedPort: summary.hostedPort });
}
return summary;
  • Give it a long timeoutSeconds. The default for a script is only 30 seconds.
  • Keep the proceedWithPublishing check. A prePublish callback can set it to false to stop the publish. The script then returns nothing, so result is empty.
  • Read the summary from result.value. It holds the same fields as the publish result.

Here's the same script as a complete command, ready for --cli-file:

command.json
{
  "command": "runNceScript",
  "projectPath": "/Users/you/Desktop/MyProject",
  "timeoutSeconds": 1800,
  "script": "const info = { configurationName: \"Web\", proceedWithPublishing: true, hostPublishedProject: false };\nawait nce.appEvents.prePublish.asyncTrigger(info);\nlet summary;\nif(info.proceedWithPublishing)\n{\n    const response = await nce.publishing.publishProject(info.configurationName, info.hostPublishedProject);\n    summary = response.payload;\n    await nce.appEvents.postPublish.asyncTrigger({ configurationName: info.configurationName, publishTimeStamp: summary.publishTimeStamp, destinationDirectory: summary.destinationDirectory, hostedPort: summary.hostedPort });\n}\nreturn summary;"
}

Screenshots from a script

For a plain image of a running project, getProjectScreenShot is the simplest choice, and getInspectorScreenShot captures the whole tab. For camera renderings, or to save screenshots as part of a larger script, use runNceScript with these functions. The project has to be running.

FunctionSaves
nce.saveProjectScreenShot(path, isPathRelative)A screenshot of the project.
nce.saveInspectorScreenShot(path, isPathRelative)A screenshot of the entire inspector.
  • path is optional. If you leave it out, the screenShotDestination value in Project Settings is used.
  • isPathRelative is optional. Set it to true if path is relative to the project.
  • Both functions return the path of the screenshot, so return that from your script to get it back as value.
Command
{ "command": "runNceScript", "projectPath": "/Users/you/Desktop/MyProject", "script": "return await nce.saveProjectScreenShot(\"ScreenShots/title.png\", true);" }

Common workflows

Using the command line from an AI agent or a script

  1. Run getSessionInfo, and filter the answer. If it fails with cliDisabled, ask the user to turn on enableCLI.
  2. Find the project in openProjects. If it's not there, run openProject.
  3. Run the commands you need, one at a time.
  4. After each one, check ok and the exit code, and read error on a failure.
  5. After a timeout or noResponse, check whether the work was done before you run the command again.

To have an agent run, see, click, type in and check a project, read the FAQ How can I have AI test my Incisor® project? in FAQs & Tutorials at incisordev.com.

Listing open projects and their configurations

This filter cuts getSessionInfo down to what a prompt needs, and keeps error:

Mac terminal
/Applications/Incisor.app/Contents/MacOS/Incisor --cli '{"command":"getSessionInfo"}' 2>/dev/null | jq '{ok, error, projects: [.result.openProjects[]? | {projectPath, isRunning, configurations: (.projectSettings.configurations // {} | keys)}]}'

What happens when Incisor® is closed

  • focusTab, getInspectorScreenShot, getProjectScreenShot and runNceScript need a window, so they fail with notOpen.
  • openProject starts Incisor® and leaves it open.
  • getSessionInfo and publish start Incisor® with no window, and it quits when the command is done.

Troubleshooting

bad option: --cli, with exit code 9

The ELECTRON_RUN_AS_NODE environment variable is set, which makes the executable behave as Node instead of Incisor®. VS Code's terminal and anything launched from a program built on Electron set it, including Claude Code in VS Code. Remove it for the command:

Mac terminal
env -u ELECTRON_RUN_AS_NODE /Applications/Incisor.app/Contents/MacOS/Incisor --cli '{"command":"getSessionInfo"}'
Windows cmd
set ELECTRON_RUN_AS_NODE=
Windows PowerShell
Remove-Item Env:ELECTRON_RUN_AS_NODE

A command hangs, or a second Incisor® starts

The command went to a different copy of Incisor® than the one that's open, for example /Applications/Incisor.app when the running copy is on the Desktop. Always use the executable inside the copy that's running. On a Mac, this shows which one that is:

Mac terminal
pgrep -fl "Incisor.app/Contents/MacOS/Incisor"

The answer is from the previous command

An old answer file was still at the --output path. Delete it before each command, or use a new file name each time.

cliDisabled, with exit code 2

Turn on enableCLI in the security group of Application Settings.

ok is false and result is missing

That's expected on a failure. Read error instead, and if you're filtering with jq, add error to the filter.

A DevTools line appears in the output

That line is on stderr, and it appears whenever the editor debugging port is on. Ignore it, or drop it with 2>/dev/null on a Mac.

A path starting with ~ isn't found

A ~ inside single quotes isn't expanded. Build the path from $HOME, as shown in Project paths above.

For the nce functions you can call from a script, see the Incisor® documentation at incisordev.com, under Documentation.