.. _ref_commands_init:

init
====

Initialise a charm operator package tree and files.

This command will modify the directory to create the necessary files for a
charm operator package. By default it will work in the current directory.

Available profiles are:
    simple:
        A basic kubernetes charm with lot of texts helping the developer
        to navigate their first charm by following the instructions.

    kubernetes:
        A basic Kubernetes charm with example container.

    machine:
        A basic charm but meant to be deployed in machine-based environments,
        without container requirements.

    flask-framework:
        A basic Flask application charm for the 12-factor charm project.

Depending on the profile choice, Charmcraft will setup the following tree of
files and directories:

    .
    ├── charmcraft.yaml            - Charm build configuration
    ├── CONTRIBUTING.md            - Instructions for how to build and develop
    │                                your charm
    ├── LICENSE                    - Your charm license, we recommend Apache 2
    ├── pyproject.toml             - Configuration for testing, formatting and
    │                                linting tools
    ├── README.md                  - Frontpage for your charmhub.io/charm/
    ├── requirements.txt           - PyPI dependencies for your charm, with `ops`
    ├── src
    │   └── charm.py               - Minimal operator using Python operator framework
    ├── tests
    │   ├── integration
    │   │   └── test_charm.py      - Integration tests
    │   ├── spread
    │   │   ├── lib
    │   │   │   └── test-helpers.sh
    │   │   └── general
    │   │       └── integration
    │   │           └── task.yaml  - Run integration tests in spread back-end
    │   └── unit
    │       └── test_charm.py      - Unit tests
    ├── spread.yaml                - Spread testing configuration file
    └── tox.ini                    - Configuration for tox, the tool to run all tests

You will need to edit at least charmcraft.yaml and README.md.

Your minimal operator code is in src/charm.py which uses the Python operator
framework from https://github.com/canonical/operator and there are some
example unit and integration tests with a harness to run them.


Usage
-----

:command:`charmcraft init [options]`


Options
-------

``--author``
   The charm author; defaults to the current user name per GECOS.
``-f`` or ``--force``
   Initialise even if the directory is not empty (will not overwrite files).
``--name``
   The name of the charm; defaults to the directory name.
``--profile``
   Use the specified project profile (defaults to 'simple').
``-p`` or ``--project-dir``
   Specify the project's directory (defaults to current).

Global options
--------------

``-h`` or ``--help``
   Show this help message and exit.
``-q`` or ``--quiet``
   Only show warnings and errors, not progress.
``-v`` or ``--verbose``
   Show debug information and be more verbose.
``--verbosity``
   Set the verbosity level to 'quiet', 'brief', 'verbose', 'debug' or 'trace'.
``-V`` or ``--version``
   Show the application version and exit.