Google Speech Recognition icon Google Speech Recognition — Google Speech for ARC: cloud speech recognition with waveform, configurable response scripts and PandoraBot support Try it →
 

Command Line

ARCx is started from a terminal (or a shortcut, a service or a startup script) and runs as a web server. The robot is controlled from a web browser pointed at the address ARCx listens on. This page explains every command line option, the environment variables ARCx reads, and how ARCx starts and stops.

Run ARCx -h to print a short version of this page.

Contents

  1. Quick reference
  2. Opening a project at start-up
  3. Password protected projects
  4. Choosing the address ARCx listens on
  5. HTTPS and certificates
  6. What happens at start-up
  7. Stopping ARCx
  8. Exit codes
  9. Examples
  10. Troubleshooting

Quick reference

ARCx [options]
Option Value What it does
-h, --help none Print the help and exit.
-f, --file project file Open this project when ARCx starts.
-p, --project-password password The password of a password protected project opened with -f.
-b, --bind URL The address the web server listens on. Default http://127.0.0.1:5000.
-c, --cert certificate file The server certificate for an https:// bind. A .pfx/.p12 bundle, or a .pem/.crt used with --cert-key.
--cert-key key file The private key file, when --cert is a .pem/.crt.
--cert-password password The password of the .pfx/.p12 bundle, or of an encrypted --cert-key.
--no-browser none Do not open the local web browser when ARCx starts. Overrides the Open a web browser when ARCx starts preference for this run, without changing it.
--mcp-stdio URL (optional) Run as the Model Context Protocol stdio bridge instead of starting ARCx: forwards stdin/stdout to a running ARCx's /mcp, http://127.0.0.1:5000/mcp unless a URL follows. For AI clients that start servers as local programs. See mcp.md.
--token token The MCP access token the bridge sends, when Preferences requires one. Only with --mcp-stdio.
Environment variable What it does
ARCX_PROJECT_PASSWORD The password of a password protected project opened with -f. Used when -p is not given.
ARCX_MCP_TOKEN The MCP access token for --mcp-stdio. Used when --token is not given; keeps the token out of the client's configuration file.
ARCX_ROBOT_BUS 1 (or true, on, yes) lets programs outside ARCx use the Robot Bus at /api/bus, whatever Options → Preferences → Robot Bus says. For a robot with no screen to turn it on from.
ARCX_ROBOT_BUS_TOKEN The access token external programs must send to the Robot Bus. Overrides the token in Options → Preferences → Robot Bus.

An option ARCx does not recognize prints the help, followed by an error naming the argument, and ARCx does not start.

On Windows the program is ARCx.exe. On Linux and macOS run it as ./ARCx from its folder.

Opening a project at start-up

ARCx -f MyRobot.arcx

-f (or --file) opens a project as soon as ARCx starts, before the web server begins listening. This is how a robot is set up to run its project unattended: start ARCx from the operating system's start-up with -f, and the project, its robot skills and its startup script are running before anybody opens a browser.

  • The value is a path to a local .arcx file. Put the path in quotes if it contains spaces.
  • Cloud projects (cloud://...) cannot be opened from the command line yet. Open them from File → Open in the user interface instead.
  • If the project cannot be opened, ARCx prints why and exits rather than starting with an empty project. That includes a project that loads with warnings, such as a robot skill that could not be installed. Open the project from the user interface once to see the warnings and fix them, then save it.
  • Without -f, ARCx starts with a new project, or whatever the home page offers.

Password protected projects

A project can be saved with a password from File → Save by ticking Password protect. The whole project file is then encrypted, and nothing in it can be read without the password. To open one from the command line, give ARCx the password in one of two ways.

With the option:

ARCx -f MyRobot.arcx -p secret

With the environment variable (recommended):

# Linux and macOS
ARCX_PROJECT_PASSWORD=secret ./ARCx -f MyRobot.arcx
:: Windows cmd
set "ARCX_PROJECT_PASSWORD=secret" && ARCx -f MyRobot.arcx
# Windows PowerShell
$env:ARCX_PROJECT_PASSWORD='secret'; .\ARCx -f MyRobot.arcx

The environment variable is the safer choice. A command line argument can be seen by other users of the computer in the process list (Task Manager, ps), and it is kept in the shell's history. An environment variable is not.

How the password is used:

  • When both are set, -p wins.
  • ARCx reads ARCX_PROJECT_PASSWORD once at start-up and then clears it, so programs and scripts that ARCx starts do not inherit the password.
  • The password is only used when the -f project is password protected. For a project that is not, it is ignored.
  • A password given without -f is ignored, and ARCx says so.
  • The password is never written to the log.
  • A password that opens the project is remembered for as long as ARCx runs. When the project is saved from the user interface, the password prompt is already filled in with it.
  • A missing password and a wrong password both stop ARCx with a message saying which it was.

In the Windows cmd example, keep the quotes around ARCX_PROJECT_PASSWORD=secret. Without them cmd includes the space before && in the password, and the password is wrong.

A forgotten project password cannot be recovered. Nothing can open the project without it.

Choosing the address ARCx listens on

ARCx -b http://0.0.0.0:5000

-b (or --bind) sets the address and port of the web server that serves the ARCx user interface.

  • The default is http://127.0.0.1:5000. It only accepts connections from the same computer.
  • http://0.0.0.0:5000 accepts connections from any computer that can reach this one, such as a phone or tablet on the same network. Browse to http://<this computer's address>:5000 from the other device.
  • To listen on one network adapter only, give that adapter's address, for example http://192.168.1.20:5000.
  • Only one address can be given. A list separated by ; is not supported.
  • If the port is already in use (for example by another copy of ARCx), ARCx fails to start. Pick another port, or stop the other program.

ARCx has no login. Anyone who can reach the address can control the robot and read or delete files through the file manager. Only bind to an address other than 127.0.0.1 on a network you trust. ARCx writes a warning to the log when it binds to anything else.

HTTPS and certificates

ARCx -b https://0.0.0.0:5001 --cert server.pfx --cert-password secret

An https:// bind encrypts the connection between the browser and ARCx. It needs a server certificate, given in one of three ways.

A PKCS#12 bundle (.pfx or .p12), which holds the certificate and its private key together:

ARCx -b https://0.0.0.0:5001 --cert server.pfx --cert-password secret

Leave out --cert-password if the bundle has no password.

A PEM certificate and key (.pem or .crt, plus a key file), as issued by Let's Encrypt and most Linux tools:

ARCx -b https://0.0.0.0:5001 --cert server.crt --cert-key server.key

If the key file is encrypted, add --cert-password with its password.

appsettings.json, without any certificate option: set Kestrel:Certificates:Default:Path (and Kestrel:Certificates:Default:Password) in the appsettings.json beside the ARCx program.

Rules ARCx checks before starting:

  • --cert with an http:// bind is refused, because the certificate would never be used.
  • An https:// bind with no certificate from any of the three sources is refused, with a list of what to supply.
  • The certificate must include its private key.
  • An expired certificate still loads, but ARCx logs a warning, because browsers will refuse to connect.

HTTPS encrypts the connection. It does not add a login; see the warning in the previous section.

What happens at start-up

In order:

  1. ARCx prints its banner and version, and reads the command line.
  2. It creates its data folders under ARCx Data in the user's Documents folder if they are missing, and starts its log.
  3. It loads the server certificate, for an https:// bind.
  4. It runs the start-up tasks, such as updating installed robot skills.
  5. It opens the -f project, if one was given.
  6. The web server starts listening, and ARCx prints Listening on <address>.
  7. ARCx opens a web browser at that address. Turn this off in Options → Preferences → Open a web browser when ARCx starts on a robot with no screen, or one you always connect to from another device. To skip it for one run without changing the preference, start ARCx with --no-browser, which wins over the preference.

Stopping ARCx

ARCx has no exit command in its user interface. Stop it from the terminal it runs in:

  • Press Ctrl+C, or close the terminal window. ARCx shuts down the robot skills, disconnects the robot controllers and closes its log. This normally takes a few seconds.
  • If shutting down hangs, press Ctrl+C a second time to exit immediately.

On Linux and macOS, kill <pid> (SIGTERM) shuts ARCx down the same way as Ctrl+C.

Exit codes

Code Meaning
0 ARCx stopped normally, or the help was printed. The help is also printed for an unrecognized argument, and that exits with 0 as well, so check the output rather than the code for a mistyped option.
1 ARCx could not start, or the -f project could not be opened. The reason is printed in the terminal and written to the log.

A start-up script or service manager can use the code to tell a failed start from a normal stop, for example to stop restarting ARCx when its project password is wrong.

Examples

Start with the default settings. Only this computer can connect:

ARCx

Open a project and let other devices on the network connect:

ARCx -f "My Robot.arcx" -b http://0.0.0.0:5000

Open a password protected project on a Linux robot, with the password kept out of the process list:

ARCX_PROJECT_PASSWORD=secret ./ARCx -f /home/robot/MyRobot.arcx -b http://0.0.0.0:5000

Open a project on a robot with no screen, without opening a web browser:

ARCx -f "My Robot.arcx" -b http://0.0.0.0:5000 --no-browser

Serve over HTTPS with a PKCS#12 bundle:

ARCx -b https://0.0.0.0:5001 --cert server.pfx --cert-password secret

Serve over HTTPS with a PEM certificate and key:

ARCx -b https://0.0.0.0:5001 --cert server.crt --cert-key server.key

Run a robot with no screen whose project is driven by programs on the network (a Python program, a ROS node through the ROS Connector), with the Robot Bus turned on and protected by a token:

ARCX_ROBOT_BUS=1 ARCX_ROBOT_BUS_TOKEN=secret ./ARCx -f /home/robot/MyRobot.arcx -b http://0.0.0.0:5000 --no-browser

The programs then connect to http://<robot>:5000/api/bus with that token, and the Python and JavaScript clients can be downloaded from the robot at /sdk/arcx_bus.py and /sdk/arcx-bus.js.

Run a second copy beside one that is already running, on another port:

ARCx -b http://127.0.0.1:5099

Troubleshooting

"The project ... is password protected. Give its password with -p/--project-password or the ARCX_PROJECT_PASSWORD environment variable." The project was saved with a password and none was given. Add -p or set the variable.

"The password for the project ... is incorrect." Check the password. In Windows cmd, check the quotes around the set command, because without them a trailing space ends up in the password. If -p is given, it overrides the environment variable.

"There are warnings attempting to load ..." The project opened, but something in it did not, such as a robot skill that could not be downloaded. Open the project from the user interface to see each warning, fix it, and save the project.

"Opening a cloud project from the command line ... is not supported yet." Use a local copy of the project with -f, or open the cloud project from the user interface.

"A certificate was specified but the bind address ... is not https." Change the bind to https://..., or remove --cert.

"Cannot bind to https://... because no server certificate is configured." Give a certificate with --cert (see HTTPS and certificates).

"ARCx failed to start on ..." Usually the port is already in use. Choose another port with -b, or stop whatever is using it. A copy of ARCx that was just closed can take a few seconds to release its port.

The browser cannot connect from another device. The default bind only accepts connections from the same computer. Start ARCx with -b http://0.0.0.0:5000 and check that the computer's firewall allows the port.

Unrecognized argument. ARCx printed the help and an error naming the argument it did not understand. Check the spelling. Options that take a value need the value after them, separated by a space.