This guide focuses on the ’tools’ subcommand. Every command that isn’t specific to a CRUD operation falls under the tools command.
There are a few utility functions that have been introduced that might be useful to the user, or is geared at managing the configuration,
switching contexts or Orgs for a given user and so on.
Authentication Management
This is mainly added as a convenience mechanism. It was needed to support some testing and exposing the feature is useful as a really simple CLI to create tokens / service Keys. You probably should be using other tooling for managing all your service files and tokens. Unlike most other entities, this is not a backup feature as much as utility.
Service Accounts
./bin/gdg tools auth svc clear delete all Service Accounts
./bin/gdg tools auth svc delete delete the given service account from grafana
./bin/gdg tools auth svc list list API Keys
./bin/gdg tools auth svc new newService <serviceName> <role> [ttl in seconds]
./bin/gdg tools auth svc new AwesomeSauceSvc admin
New Service
┌────┬─────────────────┬───────┐
│ ID │ NAME │ ROLE │
├────┼─────────────────┼───────┤
│ 4 │ AwesomeSauceSvc │ Admin │
└────┴─────────────────┴───────┘
┌────┬─────────────────┬───────┬────────┬──────────┬──────────────┬───────────────┐
│ ID │ SERVICE NAME │ ROLE │ TOKENS │ TOKEN ID │ TOKEN NAME │ EXPIRATION │
├────┼─────────────────┼───────┼────────┼──────────┼──────────────┼───────────────┤
│ 4 │ AwesomeSauceSvc │ Admin │ 1 │ │ │ │
│ │ │ │ │ 3 │ AwesomeToken │ No Expiration │
└────┴─────────────────┴───────┴────────┴──────────┴──────────────┴───────────────┘
./bin/gdg tools auth service-accounts delete 4
2025-01-26 16:54:00 INF Deleting Service Accounts for context context=testing serviceAccountId=42025-01-26 16:54:00 INF Service account has been removed serviceAccountId=4
Service Account Tokens
./bin/gdg tools auth svc tokens new <serviceAccountID> <name> [ttl in seconds]./bin/gdg tools auth svc tokens clear <serviceAccountID>
You can execute this on a single dashboard, or a folder. –autofix is available but should be considered a beta feature.
Devel
Some developer helper utilities
./bin/gdg completion [bash|fish|powershell|zsh] -- Will generate autocompletion for GDG for your favorite shell
./bin/gdg tools devel srvinfo -- print grafana server info
Helpers
A few helpers utilities added to make it easier to construct CLI regex patters
gdg tools helpers folder encode "ES net/LHC Data Challenge"
output: INF Encoded result output=ES+net/LHC+Data+Challenge
The output is what you should be using for filtering your dashboards in the configuration file.
output: INF Decoded result output=“ES net/LHC Data Challenge”
the output is what gdg will match against.
Organizations
Command can use organizations or org to set the organizations in the configuration file.
NOTE: this only manages top level of the orgs structure. Mainly used for a lazy man pattern.
./bin/gdg tools org set --orgName <name> OR --orgSlugName <name> -- Sets a given Org filter. All Dashboards and Datasources etc are uploaded to the given Org only.
Additionally addUser, updateUserRole, deleteUser, listUsers are all used to manage a user’s membership within a given organization.
Organizations Preferences
There are a few properties that can be set to change behavior. Keep in mind that all of these entity need to be owned by the Org, you cannot reference to a dashboard outside of a given org.
## will set the weekstart as Tuesday and a default Org theme of darkgdg t orgs prefs set --orgName "Main Org." --theme dark --weekstart tuesday
## Retrieve the Orgs Preferencesgdg t orgs prefs get --orgName "Main Org."
┌──────────────────┬─────────┐
│ FIELD │ VALUE │
├──────────────────┼─────────┤
│ HomeDashboardUID │ │
│ Theme │ dark │
│ WeekStart │ tuesday │
└──────────────────┴─────────┘
Organization Users CRUD
gdg tools organizations users add [OrgSlug][userID] Role[admin,editor,viewer]## Add user to org example: gdg tools organizations users add testing 3 admin
gdg tools organizations users list OrgID ## List all users for a given org example: gdg tools organizations users list 4gdg tools organizations users updateRole [OrgSlug][UserId] Role[admin,editor,viewer] example: gdg tools organizations users updateRole testing 2 admin
gdg tools organizations users currentOrg ## displays the logged in User's current associated Orggdg tools organizations users delete OrgID ## Removes a user from the given org
Users
CRUD is under the ‘backup’ command. The tools subcommand allows you to promote a given user to a grafana admin if you have the permission to do so.
NOTE: admin user is always ignored.
./bin/gdg tools users promote -u user@foobar.com -- promotes the user to a grafana admin