Skip to content
Docs
Arcus
Popular questions
↑↓ to navigate↵ to selectesc to close
Book a demo

CLI

The Arcus CLI, arcus, keeps Arcus tests in your repository as plain-text .sigma files. It checks them offline, runs a web test in a browser on your machine, and pushes tests to an Arcus project, where they appear under Test Cases.

You can use the CLI on its own, or ask a coding agent to run these commands for you.

Prerequisites

  • Node.js 22 or later, with npm. Check with node --version.
  • An Arcus account, and a project with automation turned on. Only project list, init, and push need them.
  • To run tests locally, the Arcus Agent running on your machine. It gives the CLI its browsers. The CLI’s messages call it the Testsigma agent.
  1. Install the CLI globally.

    Terminal window
    npm install -g @testsigma/arcus-cli
  2. Confirm the install. Use version 0.1.3 or later. Local runs need 0.1.1 or later.

    Terminal window
    arcus --version
  3. Sign in, with the region your Arcus account is in: us, in, or eu. The default is us. A browser tab opens for the sign-in.

    Terminal window
    arcus auth login --region us
  4. Check who you’re signed in as, and in which region.

    Terminal window
    arcus auth status

Writing, checking, and running tests don’t need a sign-in. Only project list, init, and push call Arcus. To sign out, run arcus auth logout.

arcus init binds a repository to 1 Arcus project. Run it once per project, from the repository root.

  1. List your projects. Each line shows the project ID, then its name.

    Terminal window
    arcus project list
  2. Add the project to the repository.

    Terminal window
    arcus init --project <project-id>
    OptionSetsDefault
    --dir <dir>The folder that holds the project folders, set once for the repository. Use . for a repository that holds only Arcus tests.tests/arcus
    --platforms <list>The platforms check compiles for: web, android, ios, comma-separatedweb
  3. Read the result. init reports the project, its region, and the Arcus folder that new tests go to. It creates arcus.json, adds .arcus/ to .gitignore, and creates the project folder with empty tests/ and elements/ folders.

    arcus init run from Claude Code: the project, region, and folder it reported, the .gitignore change, and the arcus.json it created, outlined

The repository then holds these files:

File or folderHoldsCommit it
arcus.jsonThe projects this repository holds, their regions, platforms, and foldersYes
arcus.lockWhich file is which Arcus test or element. The first push creates it.Yes
.arcus/Local state and run outputNo. init adds it to .gitignore.
<dir>/<project>/tests/Tests, 1 per fileYes
<dir>/<project>/elements/Elements that tests shareYes

A repository can hold several projects. Run arcus init --project <id> again for each, without --dir. Commands run at the repository root then need --project <name>, the project’s folder name. To change a project’s platforms later, run arcus project platforms add <platform> or arcus project platforms remove <platform>.

A test is 1 file in the project’s tests/ folder, holding 1 test block. It opens with the first thing a person would do and ends with a verify:

tests/arcus/my-web-app/tests/facebook-sign-in-another-account.sigma
test "Sign in with Facebook using another account" {
nav "http://localhost:3000/auth/login"
click @login/sso-facebook
verify @sso/facebook-modal visible
click @sso/use-another-account
type @sso/email-input "user@example.com"
click @sso/email-next
wait until page url ~ "/dashboard"
timeout 20s
verify @dashboard/main visible
verify page ~ "Signed in with Facebook"
}

An element is a target that tests share, in its own file under elements/. Tests use it as @<path>:

tests/arcus/my-web-app/elements/login/sso-facebook.sigma
element "login/sso-facebook" {
locator css "[data-testid='sso-facebook']"
}

Each test title must be unique in the project, ignoring case. Don’t add sub-folders under tests/.

The language is documented inside the CLI, for your project’s platforms:

Terminal window
arcus docs # every action and form, with an example
arcus docs click # 1 action
arcus docs --topic gotchas # the common mistakes
arcus docs --all # every action, with the platforms it runs on

Guide topics are project-layout, locators, elements, conditions, data, control-flow, gotchas, and word-order.

  1. Check the files. check is offline. It validates the language and the @ references, and compiles each test for every platform in the project.

    Terminal window
    arcus check

    With no paths, it checks the project’s tests/ and elements/ folders. It exits with 1 when a file has an error.

  2. Format the files into the canonical layout.

    Terminal window
    arcus fmt

    arcus fmt --check writes nothing and exits with 1 when a file would change, which suits a CI step.

A clean check means the CLI accepts the test. It doesn’t mean the test passes against your app. Run it to find out.

arcus run runs 1 web test in a browser on your machine. Nothing is sent to Arcus, and no sign-in is needed.

  1. Start the Arcus Agent, then list the browsers it offers.

    Terminal window
    arcus browsers list
  2. Run the test. The browser is hidden unless you add --headed.

    Terminal window
    arcus run tests/arcus/my-web-app/tests/facebook-sign-in-another-account.sigma
  3. Read the result: passed or failed, the browser, and the duration. A failed step keeps a screenshot in .arcus/.

OptionDoes
--headedShows the browser window
--browser <name>Runs in a browser from arcus browsers list. The default is Chrome for Testing, then Chrome.
--base-url <url>Sets {env.base_url}, for tests that open nav "{env.base_url}/path"
--var <name>=<value>Sets {env.<name>}. Repeat it for more values.
--screenshots <which>Keeps all, failed, or none of the screenshots. The default is failed.
--timeout <seconds>Stops the run after this long. The default is 300.

Pass secrets through an environment variable, not as plain text: --var password="$ARCUS_TEST_PASSWORD".

  1. Preview the push. Nothing is sent or written.

    Terminal window
    arcus push --dry-run

    The preview names the project and folder the files go to, and the result for each file: created, updated, renamed, unchanged, refused, conflict, or missing.

  2. Push.

    Terminal window
    arcus push

    Elements are sent before the tests that use them. A push that stops partway is safe to run again. It continues and doesn’t create duplicates.

  3. Commit arcus.lock with the tests. Push rewrites each file to the text Arcus holds, so review git diff first.

New tests go to the Arcus folder that init reported for the project, Default Feature in this example. They appear in Test Cases with the next test case IDs. A test that was only updated stays where it already was in Arcus.

Test Cases, with the Default Feature folder and the 5 pushed test cases outlined

Open a pushed test case to see its steps on the Automated tab, with each element as a chip.

A pushed test case, with the Automated tab and its steps outlined

Keep in mind:

  • Push doesn’t set a sprint, story, module, priority, or run result. Set them in Arcus after the push.
  • There is no pull. Arcus is the source of truth. When someone changes a test in Arcus, the push says so, and you update the file manually to match Arcus.
  • Not supported yet: api steps, groups, host lines, header lines, and sub-folders under tests/. check and push refuse them.
CommandDoes
arcus auth login [--region us|in|eu]Signs in
arcus auth statusShows who is signed in, and the region
arcus auth logoutSigns out
arcus project listLists your projects
arcus project platforms [add|remove <platform>]Lists or changes the platforms check compiles for
arcus project sources [add|remove <path>]Lists or records the source repositories a project tests
arcus init --project <id>Adds a project to the repository
arcus docs [action] [--topic <id>] [--all]Shows the actions, forms, and guides
arcus check [paths]Checks files
arcus fmt [paths] [--check]Formats files
arcus browsers listLists the browsers the Arcus Agent can drive
arcus run <test>Runs 1 web test locally
arcus push [paths] [--dry-run]Sends tests and elements to Arcus
arcus config show|set|unsetShows or changes CLI settings

check, fmt, docs, run, browsers list, project platforms, project sources, and config work without calling Arcus.

Add --json to any command for machine-readable output, and --project <name> when the repository holds several projects.

Message or symptomFix
arcus: command not foundInstall the CLI with npm install -g @testsigma/arcus-cli. It needs Node.js 22 or later.
Not signed in, or exit code 2Run arcus auth login --region <region>. A region that differs from the project’s also gives exit code 2.
Which project?The repository holds several projects. Add --project <name>, or run the command from inside the project’s folder.
A push says automation is turned offA project admin must turn on automation for the project in Arcus.
Cannot reach the Testsigma agentStart the Arcus Agent. Only run and browsers list need it. If the agent runs on another address, set it with arcus config set execution.localUrl <url>.
device runs are not supported yetThe project has no web platform. A local run tests web only.
A push is refused or in conflictThe preview names the file and the reason. Run arcus docs --topic gotchas for the common causes.

Was this page helpful?