GZ(1)

NAME
gz - Gazebo command line tool for control and analysis.

SYNPOSIS
gz command [option]... [argument]...

COMMANDS

  camera

gz camera [options]

Change properties of a camera. If a name for the world, option -w, is not specified, the first world found on the Gazebo master will be used. A camera name is required.

Options:

--verbose
    Print extra information

-h, --help
    Print this help message

-w, --world-name=arg
    World name.

-c, --camera-name=arg
    Camera name. Use gz camera -l to get a list of camera names.

-l, --list
    List all cameras

-f, --follow=arg
    Model to follow.

  debug

gz debug [options]

Used primarily for bash completion, this tool return the completion list for a given command.

Options:

--verbose
    Print extra information

-h, --help
    Print this help message

-o, --option=arg
    Show the command options.

  help

gz help [options]

Output information about a gz command.

Options:

--verbose
    Print extra information

-h, --help
    Print this help message

  joint

gz joint [options]

Change properties of a joint. If a name for the world, option -w, is not specified, the first world found on the Gazebo master will be used. A model name and joint name are required.

It is recommended to use only one type of command: force, position PID, or velocity PID.

Force: Use --force to apply a force.

Position PID: Use --pos-t to specify a target position with --pos-p, --pos-i, --pos-d to specify the PID parameters.

Velocity PID: Use --vel-t to specify a target velocity with --vel-p, --vel-i, --vel-d to specify the PID parameters.

Options:

--verbose
    Print extra information

-h, --help
    Print this help message

-w, --world-name=arg
    World name.

-m, --model-name=arg
    Model name.

-j, --joint-name=arg
    Joint name.

-f, --force=arg
    Force to apply to a joint (N).

--pos-t=arg
    Target angle(rad) for rotation joints or position (m) for linear joints.

--pos-p=arg
    Position proportional gain.

--pos-i=arg
    Position integral gain.

--pos-d=arg
    Position differential gain.

--vel-t=arg
    Target speed (rad/s for rotational joints or m/s for linear joints).

--vel-p=arg
    Velocity proportional gain.

--vel-i=arg
    Velocity integral gain.

--vel-d=arg
    Velocity differential gain.

  log

gz log [options]

Introspect and manipulate Gazebo log files. The log command can also start and stop data log recording from an active Gazebo server.

Options:

--verbose
    Print extra information

-h, --help
    Print this help message

-i, --info
    Output information about a log file. Log filename should be specified using the --file option

-e, --echo
    Output the contents of a log file to screen.

-s, --step
    Step through the contents of a log file.

-d, --record=arg
    Start/stop recording a log file from an active Gazebo server.O=stop record, 1=start recording.

-w, --world-name=arg
    World name, used when starting or stopping recording.

-r, --raw
    Output the data from echo and step without XML formatting.Used in conjuction with --echo or --step.

--stamp=arg
    Add a timestamp to each line of output. Valid values are (sim,real,wall)

-z, --hz=arg
    Filter output to the specified Hz rate.Only valid for echo and step commands.

-f, --file=arg
    Path to a log file.

-o, --output=arg
    Output file, valid in conjunction with the filter, raw, hz, and encoding commands. By default, the output file will have the same encoding as the source file. Override with the --encoding option

-n, --encoding=arg
    Specify the encoding (txt, zlib, or bz2) for an output file. Valid in conjunction with the output command. See also the --output argument.

--filter=arg
    Filter output. Valid only with the echo, step, and output commands

  marker

gz marker [options]

Add, modify, or delete visual markers.

Option Details

-a, --add: No argument

This option indicates that a marker should be added or modified. Use this in conjunction with -t to specify a marker type, -i to specify a marker id, -p to specify a parent, -f to specify a lifetime for the marker, or -n to specify a namespace.

-n, --namespace: string argument

Namespaces allow markers to be grouped. This option can be used the -a and -x command. The default namespace is empty string.

-i, --id: integer argument

Each marker has a unique id. Use this option with the -a command to assign an id to a marker. If -i is not specified, a value of zero will be used.

-t, --type: string argument

Use this command with -a to specify a marker type. The string argument must be one of: sphere, box, cylinder, line_list, line_strip, points, sphere, text, triangle_fan, triangle_list, triangle_strip.

-p, --parent: string argument

A marker can be attached to an existing visual. Use this command with -a to specify a parent visual. By default a marker is not attached to a parent visual.

-f, --lifetime: double argument

A marker's lifetime is the number of seconds that it will exist. Time starts counting when the marker is created. By default a marker has an infite lifetime.

-d, --delete: integer argument

This option will delete a single marker, if a marker exists with the specified id. The integer argument is the id of the marker to delete.

-x, --delete-all: no argument

Delete all markers.

-l, --list: no argument

List all markers.

-y, --layer: integer argument

Add or move a marker to the specified layer. Use this argument with the -a argument.

-m, --msg: string argument

Use this option to send a custom marker message. This option will override all other command line options. Details about the marker message can be found using:

$ ign msg -i ign_msgs.Marker

Example:

$ gz marker -m 'action: ADD_MODIFY, type: SPHERE, id: 2, scale: {x:0.2, y:0.4, z:1.2}'

Options:

--verbose
    Print extra information

-h, --help
    Print this help message

-a, --add
    Add or modify a visual marker

-m, --msg=arg
    Specify and send a marker message.

-n, --namespace=arg
    Namespace for the visual marker

-i, --id=arg
    Positive integer value of a visual marker

-t, --type=arg
    Type of geometry: box, cylinder, sphere, line_list, line_strip, points, text, triangle_fan, triangle_list, triangle_strip

-p, --parent=arg
    Name of a visual to which this marker should be attached.

-f, --lifetime=arg
    Simulation time the marker should last before deletion.

-d, --delete
    Delete an existing visual marker.

-x, --delete-all
    Delete all markers, or all markers in a namespace.

-l, --list
    Get a list of the visual markers.

-y, --layer=arg
    Add or move a marker to the specified layer.

  model

gz model [options]

Change properties of a model, delete a model, or spawn a new model. If a name for the world, option -w, is not pecified, the first world found on the Gazebo master will be used.

Options:

--verbose
    Print extra information

-h, --help
    Print this help message

-m, --model-name=arg
    Model name.

-w, --world-name=arg
    World name.

-d, --delete
    Delete a model.

-f, --spawn-file=arg
    Spawn model from SDF file.

-s, --spawn-string
    Spawn model from SDF string, pass by a pipe.

-i, --info
    Output model state information to the terminal.

-p, --pose
    Output model pose as a space separated 6-tuple: x y z roll pitch yaw.

-x, --pose-x arg x value

-y, --pose-y arg y value

-z, --pose-z arg z value

-R, --pose-R arg roll in radians.

-P, --pose-P arg pitch in radians.

-Y, --pose-Y arg yaw in radians.

  physics

gz physics [options]

Change properties of the physics engine on a specific world. If a name for the world, option -w, is not specified, the first world found on the Gazebo master will be used.

Options:

--verbose
    Print extra information

-h, --help
    Print this help message

-w, --world-name=arg
    World name.

-g, --gravity=arg
    Gravity vector. Comma separated 3-tuple without whitespace, eg: -g 0,0,-9.8

-s, --step-size=arg
    Maximum step size (seconds).

-i, --iters=arg
    Number of iterations.

-u, --update-rate=arg
    Target real-time update rate.

-o, --profile=arg
    Preset physics profile.

  sdf

gz sdf [options]

Introspect, convert, and output SDF files. Use the -v option to specify the version of SDF for use with other options.

Options:

--verbose
    Print extra information

-h, --help
    Print this help message

-d, --describe
    Print SDF format for given version(-v).

-c, --convert=arg
    In place conversion of arg to the latest SDF version.

-o, --doc
    Print HTML SDF. Use -v to specify version.

-k, --check=arg
    Validate arg.

-v, --version=arg
    Version of SDF to use with other options.

-p, --print=arg
    Print arg, useful for debugging and as a conversion tool.

  stats

gz stats [options]

Print gzserver statics to standard out. If a name for the world, option -w, is not specified, the first world found on the Gazebo master will be used.

Options:

--verbose
    Print extra information

-h, --help
    Print this help message

-w, --world-name=arg
    World name.

-d, --duration=arg
    Duration (seconds) to run.

-p, --plot
    Output comma-separated values, useful for processing and plotting.

  topic

gz topic [options]

Print topic information to standard out or publish a message on a topic. If a name for the world, option -w, is not specified, the first world found on the Gazebo master will be used.

Options:

--verbose
    Print extra information

-h, --help
    Print this help message

-w, --world-name=arg
    World name.

-l, --list
    List all topics.

-i, --info=arg
    Get information about a topic.

-e, --echo=arg
    Output topic data to screen.

-v, --view=arg
    View topic data using a QT widget.

-z, --hz=arg
    Get publish frequency.

-b, --bw=arg
    Get topic bandwidth.

-p, --publish=arg
    Publish message on a topic.

-r, --request=arg
    Send a request.

-u, --unformatted
    Output data from echo without formatting.

-d, --duration=arg
    Duration (seconds) to run. Applicable with echo, hz, and bw

-m, --msg=arg
    Message to send on topic. Applicable with publish and request

-f, --file=arg
    Path to a file containing the message to send on topic. Applicable with publish and request

  world

gz world [options]

Change properties of a Gazebo world on a running server. If a name for the world, option -w, is not specified the first world found on the Gazebo master will be used.

Options:

--verbose
    Print extra information

-h, --help
    Print this help message

-w, --world-name=arg
    World name.

-p, --pause=arg
    Pause/unpause simulation. 0=unpause, 1=pause.

-s, --step
    Step simulation one iteration.

-m, --multi-step=arg
    Step simulation mulitple iteration.

-r, --reset-all
    Reset time and model poses

-t, --reset-time
    Reset time

-o, --reset-models
    Reset models