4. 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 --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

4.1. Listing available cubes and instance

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

4.2. Creation of a new cube

Create your new cube cube

cubicweb-ctl newcube

This will create a new cube in /path/to/grshell-cubicweb/cubes/<mycube> for a Mercurial installation, or in /usr/share/cubicweb/cubes for a debian packages installation.

4.3. 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.

4.4. 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...)

4.5. Commands to control instances

  • start, starts one or more or all instances

of special interest:

start -D

will start in debug mode (under windows, starting without -D will not work; you need instead to setup your instance as a service).

  • stop, stops one or more or all instances
  • restart, restarts one or more or all instances
  • status, returns the status of the instance(s)

4.6. 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.

4.7. 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 Internationalization.

4.8. Other commands

  • delete, deletes an instance (configuration files and database)