{"id":20563264,"url":"https://github.com/gazebosim/gz-fuel-tools","last_synced_at":"2025-12-12T00:50:09.446Z","repository":{"id":37049616,"uuid":"255865255","full_name":"gazebosim/gz-fuel-tools","owner":"gazebosim","description":"A client library and command line tools for interacting with Gazebo Fuel servers.","archived":false,"fork":false,"pushed_at":"2025-06-06T17:53:46.000Z","size":4475,"stargazers_count":17,"open_issues_count":47,"forks_count":26,"subscribers_count":6,"default_branch":"gz-fuel-tools10","last_synced_at":"2025-06-06T18:44:52.929Z","etag":null,"topics":["asset-management","gazebo","gazebosim","hacktoberfest","ignition-fuel","ignition-robotics","robot-model","robotics","robotics-simulation"],"latest_commit_sha":null,"homepage":"https://gazebosim.org","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gazebosim.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-04-15T09:17:47.000Z","updated_at":"2025-06-06T17:52:15.000Z","dependencies_parsed_at":"2024-02-02T21:25:24.993Z","dependency_job_id":"a7cf1729-2726-47cc-936a-17e78f8bfb63","html_url":"https://github.com/gazebosim/gz-fuel-tools","commit_stats":{"total_commits":925,"total_committers":34,"mean_commits":"27.205882352941178","dds":0.8140540540540541,"last_synced_commit":"64990e387dbdf028525df4ac6b575bb43a1261d4"},"previous_names":[],"tags_count":72,"template":false,"template_full_name":null,"purl":"pkg:github/gazebosim/gz-fuel-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gazebosim%2Fgz-fuel-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gazebosim%2Fgz-fuel-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gazebosim%2Fgz-fuel-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gazebosim%2Fgz-fuel-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gazebosim","download_url":"https://codeload.github.com/gazebosim/gz-fuel-tools/tar.gz/refs/heads/gz-fuel-tools10","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gazebosim%2Fgz-fuel-tools/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260477735,"owners_count":23015060,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asset-management","gazebo","gazebosim","hacktoberfest","ignition-fuel","ignition-robotics","robot-model","robotics","robotics-simulation"],"created_at":"2024-11-16T04:17:21.594Z","updated_at":"2025-12-12T00:50:09.417Z","avatar_url":"https://github.com/gazebosim.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gazebo Fuel Tools: Classes and tools for interacting with Gazebo Fuel\r\n\r\n**Maintainer:** nate AT openrobotics DOT org\r\n\r\n[![GitHub open issues](https://img.shields.io/github/issues-raw/gazebosim/gz-fuel-tools.svg)](https://github.com/gazebosim/gz-fuel-tools/issues)\r\n[![GitHub open pull requests](https://img.shields.io/github/issues-pr-raw/gazebosim/gz-fuel-tools.svg)](https://github.com/gazebosim/gz-fuel-tools/pulls)\r\n[![Discourse topics](https://img.shields.io/discourse/https/community.gazebosim.org/topics.svg)](https://community.gazebosim.org)\r\n[![Hex.pm](https://img.shields.io/hexpm/l/plug.svg)](https://www.apache.org/licenses/LICENSE-2.0)\r\n\r\nBuild | Status\r\n-- | --\r\nTest coverage | [![codecov](https://codecov.io/gh/gazebosim/gz-fuel-tools/tree/gz-fuel-tools9/graph/badge.svg)](https://codecov.io/gh/gazebosim/gz-fuel-tools/tree/gz-fuel-tools9)\r\nUbuntu Jammy  | [![Build Status](https://build.osrfoundation.org/buildStatus/icon?job=gz_fuel_tools-ci-gz-fuel-tools9-jammy-amd64)](https://build.osrfoundation.org/job/gz_fuel_tools-ci-gz-fuel-tools9-jammy-amd64)\r\nHomebrew      | [![Build Status](https://build.osrfoundation.org/buildStatus/icon?job=gz_fuel_tools-ci-gz-fuel-tools9-homebrew-amd64)](https://build.osrfoundation.org/job/gz_fuel_tools-ci-gz-fuel-tools9-homebrew-amd64)\r\nWindows       | [![Build Status](https://build.osrfoundation.org/buildStatus/icon?job=gz_fuel_tools-9-clowin)](https://build.osrfoundation.org/job/gz_fuel_tools-9-clowin/)\r\n\r\nGazebo Fuel Tools is composed by a client library and command line tools for\r\ninteracting with Gazebo Fuel servers.\r\n\r\n  [http://github.com/gazebosim/gz-fuel-tools](http://github.com/gazebosim/gz-fuel-tools)\r\n\r\n# Building and installing\r\n\r\nSee the [installation tutorial](https://gazebosim.org/api/fuel_tools/9/install.html).\r\n\r\nMake sure `GZ_CONFIG_PATH` is set to the right install location so that `gz fuel` will work.\r\nDefault is `/usr/local/share/gz`.\r\n\r\n## Examples\r\n\r\nFor a complete list of commands run `gz fuel -h` on the command line.\r\n\r\n**List all models**\r\n```{.sh}\r\n$ gz fuel list -t model -r | head\r\nhttps://fuel.gazebosim.org/anonymous/test_model_595389531\r\nhttps://fuel.gazebosim.org/anonymous/test_model_122023392\r\nhttps://fuel.gazebosim.org/anonymous/test_model_429486665\r\nhttps://fuel.gazebosim.org/anonymous/test_model_887243621\r\nhttps://fuel.gazebosim.org/anonymous/test_model_084900530\r\nhttps://fuel.gazebosim.org/anonymous/test_model_240061059\r\nhttps://fuel.gazebosim.org/anonymous/test_model_464734097\r\nhttps://fuel.gazebosim.org/anonymous/test_model_658598990\r\nhttps://fuel.gazebosim.org/anonymous/test_model_834617935\r\nhttps://fuel.gazebosim.org/anonymous/test_model_380348669\r\n```\r\n\r\n**Download a model**\r\n```{.sh}\r\n$ gz fuel download -u https://fuel.gazebosim.org/1.0/OpenRobotics/models/Ambulance -v 4\r\nDownloading model:\r\n  Name: Ambulance\r\n  Owner: openrobotics\r\n  Server:\r\n    URL: https://fuel.gazebosim.org\r\n    Version: 1.0\r\n\r\nDownload succeeded.\r\n```\r\n\r\n**Private access tokens**\r\nPrivate models and worlds can be downloaded using access tokens.\r\nAccess tokens are generated on `app.gazebosim.org`. After logging in,\r\ngo to `Settings-\u003eAccess Tokens`.\r\n\r\nAn access token can be used with CLI commands via the `--header` option:\r\n\r\n```bash\r\n$ gz fuel download -u https://fuel.gazebosim.org/1.0/openrobotics/models/ambulance --header 'Private-Token: \u003caccess_token\u003e'\r\n```\r\n\r\nOr, an access token can be stored in a `~/.gz/fuel/config.yaml` file. The token is then\r\nautomatically used by the command line tool and API calls. Use the `configure` helper\r\ntool create your `~/.gz/fuel/config.yaml` file.\r\n\r\n```bash\r\n$ gz fuel configure\r\n```\r\n\r\n**C++ Get List models**\r\n```cpp\r\n  // Create a client (uses https://fuel.gazebosim.org by default)\r\n  gz::fuel_tools::ClientConfig conf;\r\n  gz::fuel_tools::FuelClient client(conf);\r\n  gz::fuel_tools::ModelIter iter = client.Models();\r\n  while (iter)\r\n  {\r\n    std::cout \u003c\u003c \"Got model: \" \u003c\u003c iter-\u003eIdentification().Name() \u003c\u003c \"\\n\";\r\n  }\r\n```\r\n\r\n**Upload a model**\r\n\r\nCreate an account on\r\n[https://app.gazebosim.org/](https://app.gazebosim.org/) and log\r\nin.\r\n\r\nCreate a private token at\r\n[https://app.gazebosim.org/settings#access_tokens](https://app.gazebosim.org/settings#access_tokens). Store the generated token someplace safe.\r\n\r\nThe private token can then used to upload a model:\r\n```{.sh}\r\ngz fuel upload -m ~/path_to_model --header 'Private-token: \u003cTOKEN\u003e'\r\n```\r\n\r\n## Dependencies\r\nOn ubuntu run\r\n```{.sh}\r\nsudo apt install ruby-ffi libzip-dev libcurl-dev libjsoncpp-dev\r\n```\r\n\r\n## Roadmap\r\n\r\n* Create the notion of \"asset repository\" or similar. An asset repository abstracts an entity that can store assets. It can be local or remote. This is the interface for \"asset repository\":\r\n    * List(category).\r\n        E.g.: localRepository.List(\"models\")\r\n        remote1Repository.List(\"models\")\r\n    * Details(assetIdentifier).\r\n        E.g.: Modeldentifier model;\r\n        model.Owner(\"the_owner\");\r\n        model.Name(\"the_name\");\r\n        localRepository.Details(model)\r\n        remote1Repository.Details(model)\r\n    * Create(assetIdentifier, path_to_the_asset).\r\n        E.g.: Modeldentifier model;\r\n        model.Owner(\"the_owner\");\r\n        model.Name(\"the_name\");\r\n        localRepository.Create(model, path_to_the_asset)\r\n        remote1Repository.Create(model, path_to_the_asset)\r\n    * Delete(assetIdentifier).\r\n        E.g.: Modeldentifier model;\r\n        model.Owner(\"the_owner\");\r\n        model.Name(\"the_name\");\r\n        localRepository.Delete(model)\r\n        remote1Repository.Delete(model)\r\n     * CopyTo(assetIdentifier, dst_repository).\r\n        E.g.: Modeldentifier model;\r\n        model.Owner(\"the_owner\");\r\n        model.Name(\"the_name\");\r\n        localRepository.CopyTo(model, remote1Repository)\r\n        remote1Repository.CopyTo(model, localRepository)\r\n    * \"LocalRepository\" and \"RemoteRepository\" should implement this interface.\r\n    (Most of the pieces are there, we just need to refactor the code a bit).\r\n\r\n* Think about how to detect when new versions of remote models have been uploaded.\r\n    * Idea of a hash.\r\n\r\n* Add Gazebo Fuel command line utilities for:\r\n    * detail\r\n    * create\r\n    * delete\r\n    * copyTo\r\n\r\n* How to test the client library:\r\n    * Directly against the real backend (staging?)\r\n    * Clone, and compile a local backend?\r\n    * Mocking the backend has the problem of not being in sync with the real backend and missing potential issues.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgazebosim%2Fgz-fuel-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgazebosim%2Fgz-fuel-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgazebosim%2Fgz-fuel-tools/lists"}