Gardience Documentation
gardience.com →
Docs / Administration

The gdn command line

gdn lets you work with Gardience from your own computer, in a style close to Ansible. It talks only to the Gardience REST API with your API key, so you need no SSH keys or WinRM access to the managed machines. Every change still goes through Gardience's permission checks, approvals, change windows and audit log.

Requirements

Install

Download it from your own Gardience server:

curl -fsSLo gdn https://gardience.example.com/gardience/cli/gdn && chmod +x gdn

The file contains no secrets. The console shows this command with your server's address filled in, under Settings > Command line (gdn).

Log in

./gdn login https://gardience.example.com

gdn asks for the API key, checks it by reading the license status, then saves the server address and key to ~/.config/gardience/gdn.json (or $XDG_CONFIG_HOME/gardience/gdn.json), readable only by you.

If the console uses a self-signed certificate, give gdn a copy of it so it can check the server properly:

./gdn login https://gardience.example.com --ca gardience.crt

The certificate is config/tls/gardience.crt in the install directory. --insecure turns certificate checks off completely; use it only for a quick test.

Commands

CommandWhat it does
gdn login [URL] [--ca FILE] [--insecure]Saves the server and API key.
gdn nodes [GROUP]Fleet status: node, OS, Salt version, pending updates, baseline score, and whether it is compliant. Stale nodes are marked. Give a group name to list only its members.
gdn groupsNode groups, where each comes from (built-in, custom or Ansible), and their online members.
gdn run GROUP 'COMMAND'Runs one shell command on a node group and shows each node's output. Like ansible GROUP -a 'COMMAND'.
gdn playbook FILE -l GROUP [--check] [--secrets NAMES]Uploads a local Ansible playbook and runs it on a node group over the Salt connection. --check runs it in check mode. --secrets names vault secrets to pass, separated by commas.
gdn runbooksLists the runbooks you can run and the inputs each takes.
gdn runbook ID -e key=value ...Runs any runbook. Repeat -e for each input.
gdn runsThe 20 most recent runs.
gdn status RUN_IDOne run's log.

run, playbook and runbook also take:

Examples

./gdn nodes                                 # whole fleet
./gdn nodes Windows                         # one group
./gdn run Linux 'df -h /'                   # a command on every Linux node
./gdn playbook site.yml -l web --check      # dry run of a playbook on the web group
./gdn runbook restart-service -e nodegroup=Windows -e service=Spooler --reason "print queue stuck"

Use gdn runbooks to see the real runbook IDs and inputs on your server.

Approval and waiting

If your key requires approval, gdn prints a message and waits while a second person approves the run in the console under Workflows. Press Ctrl-C to stop waiting; the run carries on and you can check it later with gdn status.

When a run finishes, gdn shows each node's result and a summary in the same layout as Ansible's PLAY RECAP.

Exit codes

CodeMeaning
0The run succeeded, or a read command worked.
1gdn could not do what you asked, for example it is not logged in, the server refused the request or could not be reached. The message starts with gdn:.
2The run finished but did not succeed.
130You pressed Ctrl-C.

Settings from the environment

These override the saved settings, which is useful in pipelines:

VariableMeaning
GARDIENCE_URLServer address, for example https://gardience.example.com.
GARDIENCE_KEYAPI key. gdn login also uses it instead of asking.
GARDIENCE_CACertificate file to trust for this server.
GARDIENCE_INSECURESet to 1 to turn certificate checks off.
NO_COLORSet to anything to turn off coloured output.
PreviousAI agents (MCP, skills, API)NextForward the audit log to a SIEM
Gardience by Bouziden Management LLC.