██████╗  █████╗ ███╗  ██╗██████╗ ██╗      ██████╗██╗     ██╗
██╔════╝ ██╔══██╗████╗ ██║██╔══██╗██║     ██╔════╝██║     ██║
██║  ███╗███████║██╔██╗██║██║  ██║██║     ██║     ██║     ██║
██║   ██║██╔══██║██║╚████║██║  ██║██║     ██║     ██║     ██║
╚██████╔╝██║  ██║██║ ╚███║██████╔╝███████╗╚██████╗███████╗██║
 ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚══╝╚═════╝ ╚══════╝ ╚═════╝╚══════╝╚═╝

A modern CLI for the Gandi v5 REST API.

Features • Quick Start • CLI Reference • Development • Authentication

---

🌟 Features

• 🌐 Domain Management — List all registered domains with expiry dates and statuses, and renew them for one or more years
• 🔧 Full DNS Control — List, create, update, and delete LiveDNS records with support for custom TTLs and all standard record types
• 🩺 Permission Doctor — Built-in gandi doctor checks your PAT scopes and shows exactly which commands are unlocked
• 🔐 PAT Authentication — Uses Gandi Personal Access Tokens with fine-grained scope control — only grant what you need
• ⚡ Rich Terminal UI — Built with Ink and React for spinners, aligned tables, and clean formatted output
• 📦 Zero Config — Set one env var or add one line to a TOML file and you're ready to go

---

🚀 Quick Start

1. Install

npm install -g @kud/gandi-cli

2. Authenticate

Generate a Personal Access Token at gandi.net → Account → Partage → Créer un jeton d'accès personnel then export it:

export GANDI_API_KEY="your-token-here"

3. Check permissions

gandi doctor

Gandi CLI
Expires in 29 days · 1 entity

✓  domain:view   gandi domain list
✗  domain:renew  gandi domain renew
✓  domain:tech   gandi dns list / set / delete

4. Manage domains and DNS

gandi domain list

gandi dns list example.com
gandi dns set example.com A www 1.2.3.4 --ttl 300
gandi dns delete example.com A www

---

📖 CLI Reference

Command	Description
gandi doctor	Check token info and permissions
gandi domain list	List all domains with expiry dates and status
gandi domain renew <domain>	Renew a domain for 1 year
gandi domain renew <domain> --duration <years>	Renew for a specified number of years
gandi dns list <domain>	List all DNS records for a domain
gandi dns set <domain> <type> <name> <value>	Create or replace a DNS record
gandi dns set <domain> <type> <name> <value> --ttl <seconds>	Set with a custom TTL in seconds
gandi dns delete <domain> <type> <name>	Delete a DNS record

---

🔧 Development

Project Structure

gandi-cli/
├── src/
│   ├── commands/
│   │   ├── doctor.tsx
│   │   ├── domain-list.tsx
│   │   ├── domain-renew.tsx
│   │   ├── dns-list.tsx
│   │   ├── dns-set.tsx
│   │   └── dns-delete.tsx
│   ├── components/
│   │   ├── error.tsx
│   │   ├── spinner-action.tsx
│   │   └── table.tsx
│   ├── lib/
│   │   ├── api.ts
│   │   └── config.ts
│   ├── types/
│   │   └── gandi.ts
│   └── index.tsx
├── dist/
├── package.json
└── README.md

Scripts

Script	Description
npm run build	Compile TypeScript to dist/
npm run dev	Run directly with tsx — no build step needed
npm run start	Run compiled output from dist/

Workflow

git clone https://github.com/kud/gandi-cli.git
cd gandi-cli
npm install
npm run dev -- doctor

---

🔒 Authentication

gandi-cli uses Personal Access Tokens (PATs) — not legacy API keys.

Generate a token at gandi.net → Account → Partage → Créer un jeton d'accès personnel with only the permissions you need:

Permission	Required for
Voir la liste de vos domaines	gandi domain list
Gérer le renouvellement de vos domaines	gandi domain renew
Accéder aux enregistrements DNS de vos domaines	gandi dns list
Gérer les enregistrements DNS de vos domaines	gandi dns set, gandi dns delete

Via environment variable (takes precedence):

export GANDI_API_KEY="your-token-here"

Via config file (~/.config/gandi/config.toml):

api_key = "your-token-here"

• ✅ Only grant permissions each command actually needs
• ✅ Set an expiry date on the token
• ✅ Use gandi doctor to verify scopes before running commands

---

🏗 Tech Stack

Component	Details
Runtime	Node.js ≥ 20
Language	TypeScript 5.x (ESM)
Terminal UI	Ink 7 + React 19
CLI Framework	Commander.js 12
Config	smol-toml
Package	npm · @kud/gandi-cli

---

MIT © kud — Made with ❤️ for the terminal

⭐ Star this repo if it saves you time · ↑ Back to top