Throughout the tutorials so far we've tried to use menus in instructions whenever possible, but on occasion you've been show a few useful tricks that are only really possible by typing commands in local chat. Learning to use the ARES command line isn't necessary for everyday use, and if you wish you may skip this tutorial entirely and just stick to using the menus. However, learning the command system is necessary to unlock the full potential of ARES.

Skip to the Next Tutorial: Updating ARES to a new version

Command Prefixes

Self-access: When you want to send a command to your own ARES system, you'll typically start by typing an "at" sign (@). This lets ARES know that you want the rest of the message to be passed on for command processing.

The @ isn't part of the command itself, though. When a command is issued by someone else (or used in a shell script), it doesn't include the @.

Local access: In earlier tutorials, we saw that anyone can attempt to use the unit's menus just by clicking on the main controller. Analogously, anyone can attempt to run a command by typing /1, then the first two letters of the unit's name, and then the command they want to run. For example, if a robot named NS f00b4r would type @persona, then its owner would type /1f0persona. This should be familiar to anyone who's used an OpenCollar, as it is the same convention.

Remote access: If you have the ARemote management console, then the behavior depends on the "shell" option under the "settings" menu:

  • input say is the default shell and causes your input to be handled the same way as the unit typing on its own. You will need to add the @ prefix to type commands, as described under "self-access," above.
  • exec interprets all of your input to behave as though you had typed @ at the start of the line. This is useful for a more traditional computing experience.
  • (none) runs the commands directly, bypassing any aliases or built-in commands in the exec interpreter. (This can be useful if the unit has a lot of aliases, or if there is some problem with exec.)
Like most things in ARES, local command access or LCA is customizable. You can change the channel (/1), the name prefix (f0), or shut it off entirely. This kind of customization is explained in Operating ARES.

What can I do with commands?

Most of the power and complexity of ARES is accessed through commands. Here are a few simpler suggestions that are of immediate utility to newer users:

  • Send a message in local chat that only the unit can see

    @echo <message>

  • Force the unit to speak a message

    @input say <message>

  • Create hotkeys to trigger commonly-used actions
    1. In your SL Inventory window, create a new Gesture
    2. Remove the default sound and animation from Steps
    3. Remove the Trigger text and Replace with text
    4. Choose a Shortcut Key
    5. Choose Chat from the Library section and click Add >>
    6. Enter the command you wish to execute, including the prefix, e.g. @echo hello
    7. Turn on the Active checkbox
    8. Save
    9. Test your new hotkey!
  • Change many more system settings

    Almost every command includes configuration options, but many of the most useful are accessed with the @db command (see below).

  • Read text files (notecards) stored inside ARES

    Use @fs to see a list of files, and @type <filename> to read one.

  • Run other downloaded text-based programs, like the ChatGPT front-end or the Mastodon social media client

    This is explained in Operating ARES: Managing Installed Software.

Command Syntax Notation

In many of the commands below, you'll see a few special punctuation marks, like [, ], |, < and > used in strange ways. Here's how to interpret them:

  • < and > indicate the start and end of a variable. You shouldn't actually type < or >, just come up with something to replace the whole term with. For example, @echo <message> means "type @echo, then a space, then some message that you want to display." The angle brackets are just there to make it clear that you aren't literally supposed to type the word "message."
  • [ and ] indicate that something is optional. Sometimes they're combined with < and >—for example, the syntax of the @persona command in everyday usage is actually @persona [<name>]. That means you can just type @persona, or optionally include the name of a persona file you want to load.
  • Finally, | (vertical bar) indicates alternative options. For example, the @power command can be used to turn on and off specific subsystems, or all subsystems at once, so its full syntax is @power [<subsystem>|all on|off|toggle]. If you know your subsystems, then this tells you that @power all on and @power video off are both valid commands. However, since those arguments are optional, you can also just type @power. This will show you the status of everything.

Sometimes what commands mean is obvious from how they're worded—we've tried to make them easy to learn, interpret, and remember. If you see a command with a bunch of parameters (multiple words), try experimenting by just typing the first word to see what happens.

More common and useful commands

  • @off shuts down the unit immediately
  • @reset <program> restarts a program that has crashed or gotten stuck
  • @persona lists available personalities
  • @persona <name> loads a personality
  • @iddqd disables or enables damage
  • @ooc toggles Out-of-Character (OOC) mode
  • @media play <animation> plays an animation from user memory

    try @media play ty.bvh

  • @media external play <sound> plays a sound by UUID

    try @media external play 8af548ab-25af-bae5-d9e1-f6fb88f8f624

  • @power all on turns on all subsystems at once
  • @help <topic> reads pages from the ARES Command Reference
  • @device shows what devices and device commands are connected
  • @charge abort stops charging (if connected to a charger—does not affect ambient charging from booths, furniture, or wireless charging nodes)
  • @security shows all users and guests

    @security reset clears all users and restores self-ownership

Special types of commands

Effector commands

Also known as ! commands (pronounced "bang" commands) or light bus commands, these are useful for creating status effects during roleplay, like sparking or faking a power-off state. These start with ! instead of @.

  • !broken enables broken effects
  • !fixed cancels broken effects
  • !working enables working effects and shows the disk throbber
  • !done cancels working effects and hides the disk throbber
  • !lamp on|off controls light emission from the controller
  • !repair starts repair effects
  • !reclaim starts reclamation (resurrection) effects
  • !repaired ends repair and reclaim effects
  • !spark plays a spark effect
  • !fault plays a series of spark effects
  • !release disables the chat redirect until the next login (type /1capture to restore normal operation)

To use an effector command remotely, it must be specified as input say !<command>, for example /1b0 input say !spark to make b0b spark.

Input directives

Input directives are a new type of ARES command that start with an equals (=) sign. These are special commands for troubleshooting, and for customizing how ARES interprets your input. For now you only need to worry about one, =ddt reset, which causes the ARES kernel to perform a full system restart of all scripts.

Unit-only commands

@on, @runaway, and @safeword are special commands that only the unit can use.

  • @on will cause the unit to start up while powered down (it can also be written as @boot)
  • @runaway will run @security reset and will work even if the unit is banned from self-access (unless the runaway security rule is disabled; see Configuring ARES for control freaks)
  • @safeword will run @restraint reset if restraint (the RLV relay) is installed, and will work even if the unit is banned from self-access (unless the runaway security rule is disabled, as above)

Dot commands

Also known as preset message or cortex bypass commands: These commands are defined by your current persona. These start with . (period) instead of @. Each one sends a piece of text to local chat. For example, .yes might say, "Yes," in your default persona, but, "Yes!" or, "You got it!" in a cheerful persona. They're called cortex bypass commands because the messages still work for the unit when its mind subsystem is disabled.

To see the available dot commands, type .info. The standard default persona includes .bye, .cannot, .error, .explain, .help, .help?, .hi, .lol, .mind, .no, .ok, .ready, .thanks, .use, .use?, .yes

To use a dot command remotely, it must be entered as input say .<command>, for example /1b0 input say .yes to make b0b say, "Yes," in the current personality's vernacular.

In some Companion documentation, "cortex bypass command" was used as a synonym for "bang commands." Technically, all of the special commands listed in this section (except aliases, below) bypass the regular input handling process.

Aliases

If you have a long command that you use often, or wish you could change the name of a command, it's possible to alias a command under another name.

  • To see the existing aliases, run the system command @alias
  • To create a new alias, run @alias <alias> <command>

    For example, @alias hi input say Hello, world!

  • To delete an alias, run @alias delete <alias>

    For example, @alias delete hi

As you can see, some of the commands we've mentioned previously are aliases. For example, @off actually tells the power program to run @power off.

Previous Tutorial: Chat: Manipulating chat messages

Next Tutorial: Updating ARES to a new version