GZ(1)

📦 version 11.10.2, in ubuntu jammy

🎀 gz(1) — bestie's guide to the gazebo command line ✨

okay so you opened the manual for gz and you came to the right place. this is the Gazebo command line tool for control and analysis, and we're gonna get through the whole thing together. boba in hand, let's go. 💖

📖 NAME

gz — Gazebo command line tool for control and analysis.

that's it. that's the whole vibe. 👑

📜 SYNPOSIS

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

so you say gz, then a command, then however many options you want, then your arguments. structure, we love her. 🦋

🧚 COMMANDS

📸 camera

gz camera [options]

this one changes the properties of a camera. if you don't tell it which world you mean with -w, it just grabs the first world it finds on the Gazebo master, no questions asked. but a camera name? required. you gotta give it one, bestie.

Options:

  • --verbose — print extra information, if you're nosy like me 🙈
  • -h, --help — print this help message
  • -w, --world-name=arg — world name.
  • -c, --camera-name=arg — camera name. psst, run gz camera -l to get a list of camera names first. 💅
  • -l, --list — list all cameras
  • -f, --follow=arg — model to follow.

🐛 debug

gz debug [options]

this one is used primarily for bash completion. you give it a command, it returns the completion list for that command. it's giving behind-the-scenes main character. ✨

Options:

  • --verbose — print extra information
  • -h, --help — print this help message
  • -o, --option=arg — show the command options.

🆘 help

gz help [options]

outputs information about a gz command. when in doubt, ask for help. no shame in it. 🫶

Options:

  • --verbose — print extra information
  • -h, --help — print this help message

🦾 joint

gz joint [options]

changes the properties of a joint. if you don't specify a world name with -w, it uses the first world found on the Gazebo master. a model name and a joint name are required.

ok so important: it is recommended to use only one type of command — force, position PID, or velocity PID. don't mix, bestie, it's not that kind of party.

here's the breakdown:

  • Force: use --force to apply a force.
  • Position PID: use --pos-t to specify a target position, along with --pos-p, --pos-i, --pos-d to specify the PID parameters.
  • Velocity PID: use --vel-t to specify a target velocity, along 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. multitasking queen. 👑

Options:

  • --verbose — print extra information
  • -h, --help — print this help message
  • -i, --info — output information about a log file. the 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. 0=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. little stickers for your sim, basically. 🌸

🔍 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 you don't name a world with -w, it grabs the first world found on the Gazebo master. (the original says "pecified" here, and honestly? relatable. we all have typos. 💀)

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. no world name with -w? you know the drill — first world found on the Gazebo master. 🌈

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]

prints gzserver statics to standard out. (yes, "statics". we're keeping it. 💜) if you don't specify a world with -w, it uses the first world found on the Gazebo master.

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 you don't specify a world name with -w, it uses the first world found on the Gazebo master. 🔥

Options:

  • --verbose — print extra information
  • -h, --help — print this help message
  • -w, --world-name=arg — the world name, bestie. that's it, that's the whole thing 🫶
  • -l, --list — show me ALL the topics, every single one, the whole roster 👑
  • -i, --info=arg — get the tea on a specific topic, drop the topic name in arg and it spills ☕
  • -e, --echo=arg — blast the topic's data straight to your screen so you can watch it go brrr 💅
  • -v, --view=arg — same idea but make it fashion: peep the topic data through a QT widget ✨
  • -z, --hz=arg — get the publish frequency, aka how often this thing is posting 📈
  • -b, --bw=arg — get the topic bandwidth, aka how chonky the data stream is 🌸
  • -p, --publish=arg — publish a message onto a topic. you're the main character now, you're the one posting 📣
  • -r, --request=arg — send a request, like sliding into the DMs but for topics 💌
  • -u, --unformatted — echo output but raw and unfiltered, no formatting, no makeup, no filter 🪞
  • -d, --duration=arg — how long (in seconds) to keep it running. only applies with echo, hz, and bw ⏱️
  • -m, --msg=arg — the actual message you're sending on the topic. applies with publish and request 💬
  • -f, --file=arg — path to a file holding the message you wanna send on the topic. also applies with publish and request 📁

🌍 world 🌍

gz world [options]

okay so this one changes the properties of a Gazebo world on a server that's already running. and here's the lil shortcut bestie needs to know: if you don't hand it a name for the world — that's option -w — it's just gonna grab the first world it finds on the Gazebo master. no questions asked, first come first served 🙈

Options:

  • --verbose — print the extra deets, give me all the context 🗣️
  • -h, --help — print this help message. classic, iconic, always there for you 🎀
  • -w, --world-name=arg — world name. yeah she's back, she's everywhere 💜
  • -p, --pause=arg — pause or unpause the simulation. 0=unpause, 1=pause. freeze frame 📸
  • -s, --step — step the simulation forward one single iteration. baby steps, one at a time 🦋
  • -m, --multi-step=arg — step the simulation mulitple iteration. (that's the original spelling bestie, i don't make the rules, i just respect them 💀)
  • -r, --reset-all — reset time AND model poses. full factory reset energy, everything back to square one 🔄
  • -t, --reset-time — reset just the time ⏰
  • -o, --reset-models — reset just the models 🧸
heads up: --pause=arg is picky — it only takes 0 for unpause or 1 for pause. no vibes-based in-between values, fr fr.

and that's the whole page, bestie!! this one's from the September 2014 era, and it's the GZ(1) manual page. go forth and slay your simulations 💖✨🎀

📦 where this page comes from