.. -*- coding: utf-8 -*-

.. _cubicweb-ctl:

``cubicweb-ctl`` tool
=====================

`cubicweb-ctl` is the swiss knife to manage *CubicWeb* instances.
The general syntax is ::

  cubicweb-ctl <command> [options command] <arguments commands>

To view available commands ::

  cubicweb-ctl
  cubicweb-ctl --help

Please note that the commands available depends on the *CubicWeb* packages
and cubes that have been installed.

To view the help menu on specific command ::

  cubicweb-ctl <command> --help

Listing available cubes and instance
-------------------------------------

* ``list``, provides a list of the available configuration, cubes
  and instances.


Creation of a new cube
-----------------------

Create your new cube cube ::

   cubicweb-ctl newcube -d <target directory>

This will create a new cube ``<target directory>``.

Create an instance
-------------------

You must ensure `~/etc/cubicweb.d/` exists prior to this. On windows, the
'~' part will probably expand to 'Documents and Settings/user'.

To create an instance from an existing cube, execute the following
command ::

   cubicweb-ctl create <cube_name> <instance_name>

This command will create the configuration files of an instance in
``~/etc/cubicweb.d/<instance_name>``.

The tool ``cubicweb-ctl`` executes the command ``db-create`` and
``db-init`` when you run ``create`` so that you can complete an
instance creation in a single command. But of course it is possible
to issue these separate commands separately, at a later stage.

Command to create/initialize an instance database
-------------------------------------------------

* ``db-create``, creates the system database of an instance (tables and
  extensions only)
* ``db-init``, initializes the system database of an instance
  (schema, groups, users, workflows...)

Run an instance
---------------

To start an instance during development, use ::

   cubicweb-ctl pyramid [-D] [-l <log-level>] <instance-id>

without ``-D``, the instance will be start in the background, as a daemon.

See :ref:`cubicweb-ctl_pyramid` for more details.

In production, it is recommended to run CubicWeb through a WSGI server like
uWSGI or Gunicorn. See :mod:`cubicweb.pyramid` more details.

Commands to maintain instances
------------------------------

* ``upgrade``, launches the existing instances migration when a new version
  of *CubicWeb* or the cubes installed is available
* ``shell``, opens a (Python based) migration shell for manual maintenance of the instance
* ``db-dump``, creates a dump of the system database
* ``db-restore``, restores a dump of the system database
* ``db-check``, checks data integrity of an instance. If the automatic correction
  is activated, it is recommanded to create a dump before this operation.
* ``schema-sync``, synchronizes the persistent schema of an instance with
  the instance schema. It is recommanded to create a dump before this operation.

Commands to maintain i18n catalogs
----------------------------------
* ``i18ncubicweb``, regenerates messages catalogs of the *CubicWeb* library
* ``i18ncube``, regenerates the messages catalogs of a cube
* ``i18ninstance``, recompiles the messages catalogs of an instance.
  This is automatically done while upgrading.

See also chapter :ref:`internationalization`.

Other commands
--------------
* ``delete``, deletes an instance (configuration files and database)