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, andpushneed 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.
Install and sign in
Section titled “Install and sign in”-
Install the CLI globally.
Terminal window npm install -g @testsigma/arcus-cli -
Confirm the install. Use version 0.1.3 or later. Local runs need 0.1.1 or later.
Terminal window arcus --version -
Sign in, with the region your Arcus account is in:
us,in, oreu. The default isus. A browser tab opens for the sign-in.Terminal window arcus auth login --region us -
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.
Set up a repository
Section titled “Set up a repository”arcus init binds a repository to 1 Arcus project. Run it once per project, from the repository root.
-
List your projects. Each line shows the project ID, then its name.
Terminal window arcus project list -
Add the project to the repository.
Terminal window arcus init --project <project-id>Option Sets Default --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 checkcompiles for:web,android,ios, comma-separatedweb -
Read the result.
initreports the project, its region, and the Arcus folder that new tests go to. It createsarcus.json, adds.arcus/to.gitignore, and creates the project folder with emptytests/andelements/folders.
The repository then holds these files:
| File or folder | Holds | Commit it |
|---|---|---|
arcus.json | The projects this repository holds, their regions, platforms, and folders | Yes |
arcus.lock | Which file is which Arcus test or element. The first push creates it. | Yes |
.arcus/ | Local state and run output | No. init adds it to .gitignore. |
<dir>/<project>/tests/ | Tests, 1 per file | Yes |
<dir>/<project>/elements/ | Elements that tests share | Yes |
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>.
Write tests and elements
Section titled “Write tests and elements”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:
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>:
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:
arcus docs # every action and form, with an examplearcus docs click # 1 actionarcus docs --topic gotchas # the common mistakesarcus docs --all # every action, with the platforms it runs onGuide topics are project-layout, locators, elements, conditions, data, control-flow, gotchas, and word-order.
Check and format
Section titled “Check and format”-
Check the files.
checkis offline. It validates the language and the@references, and compiles each test for every platform in the project.Terminal window arcus checkWith no paths, it checks the project’s
tests/andelements/folders. It exits with1when a file has an error. -
Format the files into the canonical layout.
Terminal window arcus fmtarcus fmt --checkwrites nothing and exits with1when 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.
Run a test locally
Section titled “Run a test locally”arcus run runs 1 web test in a browser on your machine. Nothing is sent to Arcus, and no sign-in is needed.
-
Start the Arcus Agent, then list the browsers it offers.
Terminal window arcus browsers list -
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 -
Read the result: passed or failed, the browser, and the duration. A failed step keeps a screenshot in
.arcus/.
| Option | Does |
|---|---|
--headed | Shows 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".
Push to Arcus
Section titled “Push to Arcus”-
Preview the push. Nothing is sent or written.
Terminal window arcus push --dry-runThe preview names the project and folder the files go to, and the result for each file:
created,updated,renamed,unchanged,refused,conflict, ormissing. -
Push.
Terminal window arcus pushElements 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.
-
Commit
arcus.lockwith the tests. Push rewrites each file to the text Arcus holds, so reviewgit difffirst.
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.

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

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:
apisteps, groups,hostlines, header lines, and sub-folders undertests/.checkandpushrefuse them.
Command reference
Section titled “Command reference”| Command | Does |
|---|---|
arcus auth login [--region us|in|eu] | Signs in |
arcus auth status | Shows who is signed in, and the region |
arcus auth logout | Signs out |
arcus project list | Lists 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 list | Lists 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|unset | Shows 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.
Troubleshooting
Section titled “Troubleshooting”| Message or symptom | Fix |
|---|---|
arcus: command not found | Install the CLI with npm install -g @testsigma/arcus-cli. It needs Node.js 22 or later. |
Not signed in, or exit code 2 | Run 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 off | A project admin must turn on automation for the project in Arcus. |
Cannot reach the Testsigma agent | Start 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 yet | The project has no web platform. A local run tests web only. |
| A push is refused or in conflict | The preview names the file and the reason. Run arcus docs --topic gotchas for the common causes. |
Was this page helpful?
Thanks for the feedback.