plonecli 7.0a4
A Plone CLI for creating Plone packages
License: BSD License
Requires Python: >=3.6
Keywords: plonecli

.. image:: https://github.com/plone/plonecli/actions/workflows/python-package.yml/badge.svg
    :target: https://github.com/plone/plonecli/actions/workflows/python-package.yml

.. image:: https://img.shields.io/pypi/v/plonecli.svg
    :target: https://pypi.python.org/pypi/plonecli/
    :alt: Latest Version

.. image:: https://img.shields.io/pypi/pyversions/bobtemplates.plone.svg?style=plastic
    :alt: PyPI - Python Version


=========
Plone CLI
=========

.. image:: https://raw.githubusercontent.com/plone/plonecli/master/docs/plone_cli_logo.svg


**A Plone CLI for creating Plone packages**

The Plone CLI is meant for developing Plone packages, we will *not* add functions to install or run Plone in production.
For this we should build another package, let's say ``plonectl`` which will provide installing and deployment functions.

It also support's GIT by default, to keep track of changes one is doing with the templates.


Installation
============

We install plonecli in the global user site-packages, so that we can use it in multiple projects.

**Versions newer than 0.1.1b4 are installable like any other package with pip**.

.. code-block:: shell

    pip install plonecli --user
    plonecli -l

To upgrade plonecli just do:

.. code-block:: shell

    pip install -U plonecli --user

**Note:** Sometimes it happens that you will have older versions of bobtemplates.plone in your system after upgrades.
The best way to solve this is, to uninstall bobtemplates.plone multiple times until it says, that there is no package installed anymore.

Make sure that the install directory is in *$PATH* (e.g. *export PATH=$PATH:$HOME/.local/bin/*)

**Note:** We are now using a the ORIGINAL version of the `CLICK <https://click.palletsprojects.com/>`_ library,
please uninstall plonecli-click before you install the new version of plonecli.

If one would like to use plonecli with pipenv, you can do it as follow:

.. code-block:: shell

    mkdir cli
    cd cli
    pipenv install plonecli
    pipenv shell
    plonecli -l

The same applies if you use other tools like pyenv virtualenv.

NOTE:
When using tools like pyenv or pipenv, you should disable the local virtualenv creation by setting *package.venv.disabled = y* in your .mrbob config file.
You can also use plonecli config to generate the config for you.

Installation on macOS
---------------------

Add the following lines to your .bash_profile. After running pip you can see where the files are located depending on your system.

.. code-block:: shell

    # plonecli
    export PATH="$HOME/Library/Python/3.7/bin:$PATH"
    source $HOME/Library/Python/3.7/bin/plonecli_autocomplete.sh


Bash Auto Completion
--------------------

To enable auto completion plonecli provides the plonecli_autocomplete.sh script, put the following bash command into your bashrc:

If you installed plonecli in user global packages:

.. code-block:: shell

    . ~/.local/bin/plonecli_autocomplete.sh

If you installed plonecli in a virtualenv it's:

.. code-block:: shell

    . /path/to/your/virtualenv/bin/plonecli_autocomplete.sh


If you used pipenv to install plonecli, you have to find out the path to the virtualenv before:

.. code-block:: shell

    pipenv --virtualenv
    /home/maik/.local/share/virtualenvs/pe-WnXOnVWH
    . /home/maik/.local/share/virtualenvs/pe-WnXOnVWH/bin/plonecli_autocomplete.sh

For other shells than BASH, like Zsh or Fish consult the click-docs:
https://click.palletsprojects.com/en/7.x/bashcomplete/#activation


Documentation
=============

Full documentation for end users can be found in the "docs" folder, this will be available in the Plone docs at some point.

**Note:** you can set default answers for mr.bob questions, see `bobtemplates.plone README <https://github.com/plone/bobtemplates.plone/#configuration>`_.

Details of the templates used by plonecli, you can find in the bobtemplates.plone documentation.
https://bobtemplatesplone.readthedocs.io

Usage
=====

Available Commands
------------------

.. code-block:: shell

    plonecli --help
    Usage: plonecli [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

      Plone Command Line Interface (CLI)

    Options:
      -l, --list-templates
      -V, --versions
      -h, --help            Show this message and exit.

    Commands:
      build         Bootstrap and build the package
      buildout      Run the package buildout
      config        Configure mr.bob global settings
      create        Create a new Plone package
      debug         Run the Plone client in debug mode
      requirements  Install the local package requirements
      serve         Run the Plone client in foreground mode
      test          Run the tests in your package
      venv          Create/update the local virtual environment...


Creating A Plone Add-on
-----------------------

.. code-block:: console

    $ plonecli -l
    Available mr.bob templates:
     - addon
      - behavior
      - content_type
      - indexer
      - portlet
      - restapi_service
      - subscriber
      - svelte_app
      - theme
      - theme_barceloneta
      - upgrade_step
      - view
      - viewlet
      - vocabulary
      - buildout

    $ plonecli create addon src/collective.todo


Adding Features To Your Plone Add-on
------------------------------------

You can add different features through subtemplates. You can use them also multiple times to create different features of the same type, like two different content types.

.. code-block:: shell

    cd collective.todo

    plonecli add behavior
    plonecli add content_type
    plonecli add theme
    plonecli add view
    plonecli add viewlet
    plonecli add vocabulary


Build Your Package
------------------

.. code-block:: shell

    plonecli build

This will run:

.. code-block:: shell

    python3 -m venv venv
    ./bin/pip install -r requirements.txt --upgrade
    ./bin/buildout bootstrap
    ./bin/buildout

in your target directory.

You can always run the 3 steps explicit by using ``venv``, ``requirements``, ``buildout`` instead of build.
If you want to upgrade/reset your build use the ``--upgrade or --clear`` option on build.

This will clear your virtualenv before installing the requirements and also running buildout with ``-n`` to get the newest versions.


Run Your Application
--------------------

.. code-block:: shell

    plonecli serve


Run Tests for Application
-------------------------

.. code-block:: shell

    plonecli test

or run specific tests:

.. code-block:: shell

    plonecli test -t test_the_thing

or run all tests including Robot tests:

.. code-block:: shell

    plonecli test --all


Combining Commands
------------------

You can combine the steps above like this:

.. code-block:: shell

    plonecli create addon src/collective.todo build test --all serve


Developer Guide
===============

Setup Developer Environment
---------------------------

.. code-block:: shell

    git clone https://github.com/plone/plonecli/
    cd plonecli
    python3 -m venv venv .
    ./venv/bin/pip install -r requirements.txt
    ./venv/bin/pip install -e .[dev,test]
    plonecli --help


Running Tests
-------------

You can run the tests using the following command:

.. code-block:: shell

    tox

or by installing py.test and run the test directly without tox:

.. code-block:: shell

    py.test test/

or a single test:

.. code-block:: shell

    py.test test/ -k test_get_package_root


Register Your Bobtemplates Package For Plonecli
-----------------------------------------------

All mr.bob templates can be registered for plonecli by adding an entry_point to your setup.py.

Here are some entry_points of the bobtemplates.plone package:

.. code-block:: python

    entry_points={
        'mrbob_templates': [
            'plone_addon = bobtemplates.plone.bobregistry:plone_addon',
            'plone_buildout = bobtemplates.plone.bobregistry:plone_buildout',  # NOQA E501
            'plone_content_type = bobtemplates.plone.bobregistry:plone_content_type',  # NOQA E501
            'plone_view = bobtemplates.plone.bobregistry:plone_view',
            'plone_viewlet = bobtemplates.plone.bobregistry:plone_viewlet',
            'plone_portlet = bobtemplates.plone.bobregistry:plone_portlet',
            'plone_theme = bobtemplates.plone.bobregistry:plone_theme',
            'plone_theme_barceloneta = bobtemplates.plone.bobregistry:plone_theme_barceloneta',  # NOQA E501
            'plone_vocabulary = bobtemplates.plone.bobregistry:plone_vocabulary',  # NOQA E501
            'plone_behavior = bobtemplates.plone.bobregistry:plone_behavior',  # NOQA E501
            'plone_restapi_service = bobtemplates.plone.bobregistry:plone_restapi_service', # NOQA E501
        ],
    },

The entry_point name is used as the global template name for mr.bob.

You also need to provide a bobregistry.py file with a method for each entry_point, it should be named after the entry_point name:

.. code-block:: python

    # -*- coding: utf-8 -*-

    class RegEntry(object):
        def __init__(self):
            self.template = ''
            self.plonecli_alias = ''
            self.depend_on = None
            self.deprecated = False
            self.info = ''


    # standalone template
    def plone_addon():
        reg = RegEntry()
        reg.template = 'bobtemplates.plone:addon'
        reg.plonecli_alias = 'addon'
        return reg


    # sub template
    def plone_theme():
        reg = RegEntry()
        reg.template = 'bobtemplates.plone:theme'
        reg.plonecli_alias = 'theme'
        reg.depend_on = 'plone_addon'
        return reg

For every template you add a line to the entry_points and define a method in the bobregistry.py, which will return a registry object with some properties.

- ``template`` - contains the name of the actual mr.bob template.
- ``plonecli_alias`` - defines the name under which the template will be used inside plonecli
- ``depend_on``:
    1. for a standalone template, the depend_on property is None
    2. for a sub template, the depend_on contains the name of the parent standalone template, usualy `addon`.
- ``deprecated`` - boolean saying whether this templates is deprecated and will be removed in future releases
- ``info`` - message that will be shown next to the template when the template is deprecated


Contribute
==========

- Issue Tracker: https://github.com/plone/plonecli/issues
- Source Code: https://github.com/plone/plonecli


License
=======

This project is licensed under the BSD license.

History
=======

7.0a4 (2025-08-20)
------------------

- add --non-interactive parameter
  [MrTango]


7.0a3 (2025-08-20)
------------------

- fix tmplate registry
  [MrTango]


7.0a2 (2025-05-30)
------------------

- fix lookup of bobtemplates-plone templates
  [MrTango]


7.0a1 (2025-05-30)
------------------

- bump bobtemplates.plone dependency to 7.0.0a1
  [MrTango]


2.5 (2022-11-03)
----------------

- Provide a way to pass a mrbob configuration file
  [erral]

2.4 (2022-10-10)
----------------

- Depend on bobtemplates.plone >=6.0b15 ;)


2.3 (2022-10-08)
----------------

- Depend on bobtemplates.plone >=6.0b16


2.2 (2022-05-04)
----------------

- Remove dependency on ``virtualenv``.
  [wesleybl]

- Rename deprecated ``autocompletion`` parameter to ``shell_complete``
  [zshashz]


2.1.2 (2021-05-06)
------------------

- Fix broken releases 2.1/2.1.1
  [MrTango]


2.1.1 (2021-05-05)
------------------

- Fix setup.cfg - v2.1 is a brown bag release.
  [jensens]

- Improve README
  [svx]


2.1 (2021-05-05)
----------------

- Call mr.bob using its API, no longer as subprocess.
  This ease the usage in a virtualenv.
  [jensens]

- Do not install zest.releaser with plonecli (keep for dev/tox).
  [jensens]

- Do not install virtualenv if not Python 2.7
  [jensens]


2.0 (2020-12-10)
----------------

- Release


2.0b1 (2020-11-20)
------------------

- Add alias upport and an alias for "virtualenv" for the venv command
  [MrTango]

- Improve handling of global/local commands, we use ClickFilteredAliasedGroup to filter the command rather than using an if condition in code.
  [MrTango]


2.0a2 (2020-11-19)
------------------

- Fix #63 generate_mrbob_ini and the acconding tests
  [MrTango]

- Drop Python2.7 support and remove it from tox and travis setup. Also improve linting with new isort and black.
  [MrTango]

- Add config command to disable the venv creation/update on plonecli build command
  [MrTango]

- Allow auto completion of template names
  [MrTango]

- Improve mrbob config generation and now override an existing config file after a warning
  [MrTango]

- Fix typos, ReST formatting and update content of README.rst.
  [staeff]


1.1 (2019-04-14)
----------------

- Add new build option -p to define the python binary to use for the virtualenv
  [MrTango]


1.0 (2019-03-08)
----------------

- add note for including install directory to $PATH
  [fgrcon]

- Document the new `deprecated` and `info` options
  [erral]

- modernize code for Python 3 support
  [MrTango]


0.3.0 (2018-10-17)
------------------

- Sort templates on --list-templates/-l command output
  [MrTango]

- Show deprecate flag and info for templates in template list
  [MrTango]

- Use the now released click library in version >= 7.0, you have to uninstall plonecli-click before upgrading!
  [MrTango]

0.2.2 (2018-08-13)
------------------

- Add -t and -s options to the test command
  [kakshay21]

- Fix #33 ConfigParser.NoOptionError
  [kakshay21]


0.2.1 (2018-07-09)
------------------

- Add plonecli config command to configure mrbob's global user settings
  [kakshay21]

- Add versions -V/--versions command
  [kakshay21]

- Add document commends -h, -V, test and config in README
  [kakshay21]


0.2.0 (2018-04-03)
------------------

- Add test command to allow running test from plonecli
  [MrTango]


0.1.1 (2018-03-28)
------------------

- Improve command line output with colors and remove verbose option
  [MrTango]

- Add virtualenv as requirement and improve README
  [MrTango]


0.1.1b6 (2018-03-28)
--------------------

- fix autocomletion for top level commands
  [MrTango]


0.1.1b5 (2018-03-27)
--------------------

- use bobtemplates.plone>=3.0.0b5
  [MrTango]


0.1.1b4 (2018-03-26)
--------------------

- Use a forked version of click library (plonecli-click) as dependency for now
  [MrTango]


0.1.1b3 (2018-03-23)
--------------------

- Fix broken release


0.1.1b2 (2018-03-22)
--------------------

- Fix dist on pypi


0.1.1b1 (2018-03-22)
--------------------

- Add requirements.txt referencing the special Click version.
  This makes a ``pip`` installation possible.
  [jensens]
- Refactored registry to use the new bobtemplate.cfg
  [MrTango]


0.1.0a4 (2017-10-30)
--------------------

- provide plonecli_autocomplete.sh for bash autocompletion
  [MrTango]
- fix depency to bobtemplates.plone, we need >=3.0.0a3
  [MrTango]


0.1.0a3 (2017-10-24)
--------------------

- Update README to use easy_install instead of pip for now
  [MrTango]


0.1.0a2 (2017-10-24)
--------------------

- fix setup.py to use the github version of click, until click >6.7 is released
  [MrTango]


0.1.0a1 (2017-10-24)
--------------------

- initital version with list templates support and bobtemplates.plone integration
  [MrTango, tmassman, Gomez]