Skip to main content

Gandi command line interface

Project description

# Gandi CLI

Use `$ gandi` to easily create and manage web resources from the command line.

* `$ gandi domain` to buy and manage your domain names
* `$ gandi paas` to create and deploy your web applications
* `$ gandi vm` to spin up and upgrade your virtual machines
* `$ gandi` to list all available commands
* [Detailed examples](#use-cases)
* [All commands](#all-commands)

## Table of contents

* [Requirements](#requirements)
* [Installation](#installation)
* [Getting started](#getting-started)
* [Use cases](#use-cases)
* [Registering a Domain Name](#registering-a-domain-name)
* [Creating a Virtual Machine](#creating-a-virtual-machine)
* [Deploying a Web Application](#deploying-a-web-application)
* [Advanced Usage](#advanced-usage)
* [All Commands](#all-commands)
* [Build manpage](#build-manpage)
* [Configuration](#configuration)
* [Development](#development)
* [Contributing](#contributing)
* [License](#license)

## Requirements

* A compatible operating system (Linux, BSD, Mac OS X/Darwin, Windows)
* Python 2.6/2.7 (Python 3 not yet supported)

Recommended tools
* [pip](https://pip.pypa.io/en/latest/installing.html)
* [virtualenv](https://pypi.python.org/pypi/virtualenv)

## Installation

### Install with pip and virtualenv

$ virtualenv /some/directory/gandi.cli
$ source /some/directory/gandi.cli/bin/activate
$ pip install gandi.cli

### Build from source

$ cd /path/to/the/repository
$ python setup.py install --user

### From the Debian package

$ ln -sf packages/debian debian && debuild -us -uc -b && echo "Bisou"

## Getting started

1. To get started, you can create a [free Gandi account](https://www.gandi.net/contact/create) and get your Gandi Handle
2. [Generate your Production API Token](https://www.gandi.net/admin/api_key) from the account admin section
3. You may also want to [top-up your prepaid account](https://www.gandi.net/prepaid)

Then run the setup

$ gandi setup
> API Key: x134z5x4c5c # copy-paste your api key
> Environment [production] : # press enter for Production, the default
> SSH key [~/.ssh/id_rsa.pub] : # your SSH public key for hosting instances and servers

See the [Advanced Usage](#advanced-usage) section for more details on configuration.

## Use cases

* [Registering a domain name](#registering-a-domain-name)
* [Creating a virtual machine](#creating-a-virtual-machine)
* [Deploying a web application](#deploying-a-web-application)

### Registering a Domain Name

Gandi is a domain name registrar since 1999. The oldest in France and one of the world's leading, Gandi is recognized for its No Bullshit™ trademark and approach to domain names.

You can now buy and manage domains in any of the 500+ TLD's that Gandi offers from the command line.

[Know more about Gandi Domains on the website](https://www.gandi.net/domain).

#### 1. Buy a domain using the interactive prompt

$ gandi domain create
> Domain: example.com # enter the domain name here
> example.com is available
> Duration [1] : 1 # enter the duration in years

This will create a domain and use your default information for Ownership, Admin, Technical and Billing info.


#### 2. Buy a domain in one line

$ gandi domain create --domain example.com --duration 1

#### 3. Buy a domain with custom contacts

$ gandi domain create --domain example.com --duration 1 --owner XYZ123-GANDI --admin XYZ123-GANDI --tech XYZ123-GANDI --bill XYZ123-GANDI

You can use the information of Gandi handles associated to Contacts in your account to setup Owner, Admin, Technical and Billing info.

#### 3. List your domains

$ gandi domain list

#### 4. Get information about a domain

$ gandi domain info example.com

### Creating a Virtual Machine

Gandi Server offers powerful Xen- and Linux-based virtual machines since 2007.

Virtual machines can be configured and upgraded on the fly to your liking. For example, you can start with 1GB of RAM, and run a command to add 2GB of RAM and 2 CPUs without even having to restart it.

Gandi Server measures consumption by the hour and uses a prepaid credit system. To learn more, [check out the Gandi Server website](https://www.gandi.net/hosting/server/).

#### 1. Create and access a VM

$ gandi vm create
> datacenter: FR
> memory: 256
> cores: 1
> ip_version: 4
> bandwidth: 102400
> login: admin
> hostname: tempo

Create a virtual machine with the default configuration and a random hostname.

#### 2. Upgrade a VM

$ gandi vm update tempo --memory 2024 --cores 2

Set the VM's RAM to 2GB and add a CPU core on the fly.

#### 3. Create a custom VM

$ gandi vm create --datacenter US --hostname docker --cores 2 --ram 3036GB --disk 10GB --image "Ubuntu 14.04 64 bits" --run "curl -s https://get.docker.io/ubuntu | sh"
> datacenter: US
> memory: 3036
> cores: 2
> ip_version: 4
> bandwidth: 102400
> login: admin
> hostname: docker
> image: Ubuntu 14.04 64 bits

This command will setup the above VM, and install docker by running `curl -s https://get.docker.io/ubuntu | sh` after creation.

#### 4. View your ressources

$ gandi vm list

#### 5. Get all the details about a VM

$ gandi vm info docker


### Deploying a Web Application

Gandi Simple Hosting is a PaaS (Platform as a Service) offering fast code deployment and easy scaling, powering over 50,000 apps since its inception in 2012.

Instances can run apps in 4 languages (PHP, Python, Node.js and Ruby) along with one of 3 popular databases (MySQL, PostgreSQL and MongoDB) and operate on a managed platform with built-in http caching.

Plans cover all scales, from small to world-class projects. [Check out the website for more information](https://www.gandi.net/hosting/simple).

#### 1. Create an instance for your app


$ gandi paas create --name myapp --type phpmysql --size S --datacenter FR --duration 1


#### 2. Update code and deploy

$ cd myapp
$ git init .
$ git add .
$ git commit -m 'first commit'
$ git push gandi master
$ gandi deploy


## Advanced Usage

### All Commands

To list all available commands, type `$ gandi --help`

For extended instructions, check out the `man` page.

### Build manpage

Install python-docutils and run:

$ rst2man --no-generator gandicli.man.rst > gandi.1.man

Then to read the manpage:

$ man ./gandi.1.man

### Configuration

Run `$ gandi setup` to configure your settings (see [Getting started](#getting-started))

Use `$ gandi config` to set and edit custom variables.
The default variables are:
* `sshkey` # path to your public ssh key
* `api.host` # the URL of the API endpoint to use (i.e OTE or Production)
* `api.key` # the relevant API key for the chosen endpoint

### Development

To add a new command to the CLI:
* check if there's an existing namespace to either add a command or an option to an already existing one
* each command is composed of 2 python files, located in the `commands/` and `modules/` directories
* `commands/` contains everything that is related to shell arguments, parameter validation, default values
* `modules/` contains code that uses the Gandi API and can be used by other python scripts, or in the python shell.
* `packages/` contains packaging code (see `packages/README.rst`)

Code must follow PEP8 recommendations: http://legacy.python.org/dev/peps/pep-0008/
Docstrings should follow PEP257 recommendations: http://legacy.python.org/dev/peps/pep-0257/


## Contributing

Create a git branch with your new feature or bugfix and either:
* mail the patch to feedback@gandi.net,
* send the URL for your branch and we will review/merge it if correct,
* open a merge request on GitHub

## License / Copying

Copyright © 2014 Gandi S.A.S

Gandi CLI is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

Gandi CLI is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with Gandi CLI. If not, see <http://www.gnu.org/licenses/gpl.txt>.


Changelog
=========

0.8
---

* New record namespace to manage domain zone record entries

0.7
---

* Add and update License information to use GPL-3
* Uniformize help strings during creation/deletion commands

0.6
---

* New mail namespace for managing mailboxes and aliases
* New command 'disk create' to create a virtual disk
* New command 'vm ssh' to open a ssh connection to an existing
virtual machine
* New command 'help' which behave like --help option.
* Using 'gandi namespace' without full command will display list
of available commands for this namespace and associated short help.
* 'gandi paas create' and 'gandi vm create' commands now use sshkeys,
and default to LU as default datacenter.

0.5
---

* Fixes Debian packaging


0.4
---

* Fixes bug with snapshotprofile list command preventing
'gandi setup' to work after clean installation
* Allow Gandi CLI to load custom modules/commands using
'GANDICLI_PATH' environment variable

0.3
---

* New certificate namespace for managing certificates
* New disk namespace for managing iaas disks
* New snapshotprofile namespace to know which profiles exists
* Allow override of configuration values for apikey, apienv and apihost
using shell environment variables API_KEY, API_ENV, API_HOST.
* Bugfixes on various vm and paas commands
* Fixes typos in docstrings
* Update man page

0.2
---

* New vhost namespace for managing virtual host for PaaS instances
* New sshkey namespace for managing a sshkey keyring
* Bugfixes on various vm and paas commands
* Bugfixes when using a hostname using only numbers
* Added a random unique name generated for temporary VM and PaaS


0.1
---

* Initial release

Project details


Release history Release notifications

History Node

1.2

History Node

1.1

History Node

1.0

History Node

0.22

History Node

0.21

History Node

0.20

History Node

0.19

History Node

0.18

History Node

0.17

History Node

0.16

History Node

0.15

History Node

0.14

History Node

0.13

History Node

0.12

History Node

0.11

History Node

0.10

History Node

0.9

History Node

0.8

This version
History Node

0.7

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
gandi.cli-0.7.tar.gz (105.9 kB) Copy SHA256 hash SHA256 Source None Sep 5, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page