Metadata-Version: 1.1
Name: gandi.cli
Version: 0.12
Summary: Gandi command line interface
Home-page: https://github.com/Gandi/gandi.cli
Author: Gandi
Author-email: feedback@gandi.net
License: UNKNOWN
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)
          * [Code status](#code-status)
          * [License](#license)
        
        ## Requirements
        
        * A compatible operating system (Linux, BSD, Mac OS X/Darwin, Windows)
        * Python 2.6/2.7/3.2/3.3/3.4
        
        Recommended tools
        * [pip](https://pip.pypa.io/en/latest/installing.html)
        * [virtualenv](https://virtualenv.pypa.io/en/latest/virtualenv.html#installation)
        
        ## 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)
        4. To manipulate VM's, you also need to [purchase credits](https://www.gandi.net/credit/buy) (you can use funds from your prepaid account)
        
        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
        
        #### 5. List NS records of a domain
            $ gandi record list example.com
        
        You can use `--output` to extract your zone records in a file, then edit it and use `gandi record update example.com -f file` to update it easily.
        
        ### 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
            * root user will be created.
            * SSH key authorization will be used.
            * No password supplied for vm (required to enable emergency web console access).
            * Configuration used: 1 cores, 256Mb memory, ip v4+v6, image Debian 7, hostname: temp1415183684
        
        Create a virtual machine with the default configuration and a random hostname.
        
        #### 2. Upgrade a VM
        
            $ gandi vm update temp1415183684 --memory 2048 --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 --memory 3072 --size 10240 --image "Ubuntu 14.04 64 bits LTS (HVM)" --run "curl -sSL https://get.docker.com/ubuntu/ | sh"
            * root user will be created.
            * SSH key authorization will be used.
            * No password supplied for vm (required to enable emergency web console access).
            * Configuration used: 2 cores, 3072Mb memory, ip v4+v6, image Ubuntu 14.04 64 bits LTS, hostname: docker
        
        This command will setup the above VM, and install docker by running `curl -sSL https://get.docker.com/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://www.python.org/dev/peps/pep-0008/
        
        Docstrings should follow PEP257 recommendations: http://www.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
        
        ## Code status
        
        [![Build Status](https://travis-ci.org/Gandi/gandi.cli.svg?branch=master)](https://travis-ci.org/Gandi/gandi.cli)
        
        ## 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.12
        ----
        
        * New 'ip' namespace with commands for managing public/private ip resources.
        * New 'vlan' namespace with commands for managing vlans for virtual machines.
        * New command 'gandi account info' to display information about credits
          amount for hosting account.
        * New command 'gandi contact create' to create a new contact.
        * New command 'gandi disk snapshot' to create a disk snapshot on the fly.
        * Update 'gandi vm create' command:
            - enabling creation of vlan and ip assignment for this vlan directly
              during vm creation.
            - enabling creation of a private only ip virtual machine.
            - parameter --ip-version is not read from configuration file anymore,
              still defaulting to 4.
        * Update 'gandi paas create' command to allow again the use of password provided
          on the command line.
        * Update 'record' namespace to add delete/update commands, with option to export
          zones to file.
        * Use different prefix for temporary names based on type of resource.
        * Switch to use HVM image as default disk image when creating virtual machine.
        * Add kernel information to output of 'gandi disk list' command.
        * Fixes bug with paas vhost directory creation.
        * Fixes bug with 'gandi mail delete' command raising a traceback.
        * Fixes bug with duplicates entries in commands accepting multiple resources.
        * Fixes various typos in documentation and help pages.
        * Add first batch of unittests.
        
        
        0.11
        ----
        
        * New command 'gandi disk detach' to detach disks from
          currently attached vm.
        * New command 'gandi disk attach' to attach disk to a
          vm.
        * New command 'gandi disk rollback' to perform a rollback
          from a snapshot.
        * New parameter --source for command 'gandi disk create'
          to allow creation of a new disk from an existing disk
          or snapshot.
        * New parameter --script for command 'gandi vm create'
          to allow upload of a local script on freshly created vm
          to be run after creation is completed.
        * Update parameter --size of 'gandi disk create/update'
          command to accept optionnal suffix: M,G,T (from megabytes
          up to terabytes).
        * Update command 'gandi vm ssh' to accept args to be passed
          to launched ssh command.
        * Fixes bug with 'gandi vm create' command and image
          parameter, which failed when having more than 100 disks
          in account.
        * Fixes bug with 'gandi paas info' command to display
          sftp_server url.
        * Fixes bug with 'gandi record list' command when requesting
          a domain not managed at Gandi.
        * Rename --sshkey parameter of 'gandi sshkey create' command
          to --filename.
        * Prettify output of list/info commands.
        * GANDI_CONFIG environment variable can be used to override
          the global configuration file.
        * Bump click requirement version to <= 4.
        
        
        0.10
        ----
        
        * Add new dependency to request library, for certificate
          validation during xmlrpc calls.
        * New command 'gandi vm kernels' to list available kernels,
          can also be used to filter by vm to know which kernel is
          compatible.
        * New parameters --cmdline and --kernels for command
          'gandi disk update' to enable updating of cmdline
          and/or kernel.
        * New parameter --size for command 'gandi vm create'
          to specify disk size during vm creation.
        * Handle max_memory setting in command 'gandi vm update'
          when updating memory. New parameter --reboot added to
          accept a VM reboot for non-live update.
        * Update command 'gandi vm images' to also display usable
          disks as image for vm creation.
        * Security: validate server certificate using request as
          xmlrpc transport.
        * Security: restrict configuration file rights to owner only.
        * Refactor code of custom parameters, to only query API when
          needed, improving overall speed of all commands.
        * Fixes bug with sshkey parameter for 'gandi paas create'
          and 'gandi paas update' commands.
        * When an API call fail, we can call again using dry-run flag
          to get more explicit errors. Used by 'gandi vhost create'
          command.
        * Allow Gandi CLI to load custom modules using
          'GANDICLI_PATH' environment variable, was previously only
          done by commands.
        
        
        0.9
        ---
        
        * New command 'gandi docker' to manage docker instance.
          This requires a docker client to work.
        * Improve 'vm ssh' command to support identity file, login@
          syntax.
        * Login is no longer a mandatory option and saved to configuration
          when creating a virtual machine.
        * Add short summary to output when creating a virtual machine.
        * Fixes bug when no sshkey available during setup.
        * Fixes bug with parameters validation when calling a command
          before having entered api credentials.
        
        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
        
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Terminals
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
