cmd_init.rst

pio project init

Contents

• Usage
• Description
• Options
• Examples

Usage

pio project init [OPTIONS]

Description

Initialize a new PlatformIO based project or update existing with new data.

This command will create:

• :ref:`projectconf`
• :ref:`projectconf_pio_include_dir`, put project header files here
• :ref:`projectconf_pio_src_dir`, put project source files here (*.h, *.c, *.cpp, *.S, *.ino, etc.)
• :ref:`projectconf_pio_lib_dir`, put project specific (private) libraries here. See also :ref:`ldf`
• :ref:`projectconf_pio_test_dir`, put project tests here. More details :ref:`unit_testing`
• Miscellaneous files for VCS and :ref:`ci` support.

Options

.. program:: pio project init

.. option::
    -d, --project-dir

A path to a directory where PlatformIO will initialize new project.

.. option::
    -b, --board

If you specify board ID (you can pass multiple --board options), then PlatformIO will automatically generate environment for :ref:`projectconf` and pre-fill these data:

• :ref:`projectconf_env_platform`
• :ref:`projectconf_env_framework`
• :ref:`projectconf_env_board`

The full list with pre-configured boards is available here :ref:`platforms`.

.. option::
    --ide

Initialize PlatformIO project for the specified IDE which can be imported later via "Import Project" functionality.

A list with supported IDE is available within pio project init --help command. Also, please take a look at :ref:`ide` page.

.. option::
    -e, --environment

Update project using existing environment.

.. option::
    -O, --project-option

Initialize project with additional options from :ref:`projectconf`. For example, pio project init --project-option="lib_deps=ArduinoJSON". Multiple options are allowed.

.. option::
    --env-prefix

An environment prefix which will be used with pair in :ref:`projectconf_env_board` ID. For example, the default environment name for :ref:`board_teensy_teensy31` board will be [env:teensy31].

.. option::
    --no-install-dependencies

Do not resolve project dependencies and do not install missed packages.

.. option::
    --sample-code

.. versionadded:: 6.1.7

Include sample code in the newly created project. The availability of sample code depends on the :ref:`platforms` being used.

.. option::
    -s, --silent

Suppress progress reporting.

Examples

1. Initialize new project in a current working directory

> pio project init

The current working directory *** will be used for the new project.
You can specify another project directory via
`pio project init -d %PATH_TO_THE_PROJECT_DIR%` command.

The following files/directories will be created in ***
platformio.ini - Project Configuration File. |-> PLEASE EDIT ME <-|
src - Put your source files here
lib - Put here project specific (private) libraries
Project has been successfully initialized!
Useful commands:
`pio run` - process/build project from the current directory
`pio run --target upload` or `pio run -t upload` - upload firmware to embedded board
`pio run --target clean` - clean project (remove compiled files)

2. Initialize new project in a specified directory

> pio project init -d %PATH_TO_DIR%

The following files/directories will be created in ***
 platformio.ini - Project Configuration File. |-> PLEASE EDIT ME <-|
...

3. Initialize project for Arduino Uno

> pio project init --board uno

The current working directory *** will be used for the new project.
You can specify another project directory via
`pio project init -d %PATH_TO_THE_PROJECT_DIR%` command.
...

4. Initialize project for Teensy 3.1 board with custom :ref:`framework_mbed`

> pio project init --board teensy31 --project-option "framework=mbed"

The current working directory *** will be used for the new project.
You can specify another project directory via
`pio project init -d %PATH_TO_THE_PROJECT_DIR%` command.

...

5. Initialize a new project passing working environment name and its options

> pio project init --environment native --project-option="platform=native" --project-option="build_flags=-DRELEASE=1"

The current working directory *** will be used for the new project.
...