Understanding the structure of ICE Agent commands
The ICE Agent command-line utility provides a wealth of functionality.
agent <agent-switches> [command <command-switches> [subcommand <subcommand-switches>]]
A switch refers to a parameter passed on the command line and proceeded with one or two dashes. For example, when executing agent --version, the --version switch applies to the agent command and tells the agent to display information about its version and exit. Oftentimes a switch will require a parameter of its own. For example, when executing agent -l all --version, the -l argument tells the agent command to change the verbosity level of the log messages it produces. In this case, the -l switch requires that it be immediately followed by the name of a verbosity level such as all.
A command or subcommand refers to a parameter passed on the command line that is not proceeded with dashes. Commands and subcommands select the Agent’s mode of operation. For example, agent external rallypoint tells the ICE Agent to operate as an external (ICE Server-managed) Rallypoint. When parsing this, external is a command to agent, and rallypoint is a subcommand of external.
Because of the hierarchical relationship between commands and subcommands, the order in which they appear on the command-line is important. Calling agent external rallypoint is not the same as invoking agent rallypoint external.
Furthermore, switches are applied to the command or subcommand that directly precedes them (to the left). In a previous example, agent --version we saw that the --version switch applied to the agent command. The command agent external rallypoint --version would attempt to apply the --version switch to the rallypoint subcommand (which it does not accept). In short, commands, subcommands, and switches are all sensitive to their placement in the command line.
Important: Commands, subcommands, and switches are case sensitive.
ICE Agent Help Switch
ICE Agent has a special switch, --help, that can be placed anywhere on the command line. When present, it causes ICE Agent to display information about available commands and switches and exit.
While the --help switch can be applied anywhere, the informational text displayed refers to the command or subcommand which received the --help switch. For example, agent --help displays information about commands and switches that can be applied to agent whereas agent external --help rallypoint displays information about the external command. Why show help for the external command and not the rallypoint subcommand? Because the first command appearing to the left of --help is external, not rallypoint.