Skip to content

cli.py

Command line entrypoint. This module declares the Copier CLI applications.

Basically, there are 3 different commands you can run:

  • copier, the main app, which is a shortcut for the copy and update subapps.

    If the destination project is found and has an answers file with enough information, it will become a shortcut for copier update.

    Otherwise it will be a shortcut for copier copy.

    Example

    # Copy a new project
copier gh:copier-org/autopretty my-project
# Update it
cd my-project
copier

  • copier copy, used to bootstrap a new project from a template.

    Example

    copier copy gh:copier-org/autopretty my-project

  • copier update to update a preexisting project to a newer version of its template.

    Example

    copier update

Below are the docs of each one of those.

CLI help generated from copier --help-all:

copier 0.0.0

Create a new project from a template.

Docs in https://copier.readthedocs.io/

WARNING! Use only trusted project templates, as they might execute code with the
same level of access as your user.


Usage:
    copier [SWITCHES] [SUBCOMMAND [SWITCHES]] args...

Meta-switches:
    -h, --help         Prints this help message and quits
    --help-all         Prints help messages of all sub-commands and quits
    -v, --version      Prints the program's version and quits

Sub-commands:
    copy               Copy from a template source to a destination.; see
                       'copier copy --help' for more info
    recopy             Recopy a subproject from its original template; see
                       'copier recopy --help' for more info
    update             Update a subproject from its original template; see
                       'copier update --help' for more info

copier copy 0.0.0

Copy from a template source to a destination.

Usage:
    copier copy [SWITCHES] template_src destination_path

Hidden-switches:
    -h, --help                      Prints this help message and quits
    --help-all                      Prints help messages of all sub-commands and
                                    quits
    -v, --version                   Prints the program's version and quits

Switches:
    -C, --no-cleanup                On error, do not delete destination if it
                                    was created by Copier.
    -T, --skip-tasks                Skip template tasks execution
    --UNSAFE, --trust               Allow templates with unsafe features (Jinja
                                    extensions, migrations, tasks)
    -a, --answers-file VALUE:str    Update using this path (relative to
                                    `destination_path`) to find the answers file
    -d, --data VARIABLE=VALUE:str   Make VARIABLE available as VALUE when
                                    rendering the template; may be given
                                    multiple times
    --data-file PATH:ExistingFile   Load data from a YAML file
    -f, --force                     Same as `--defaults --overwrite`.
    -g, --prereleases               Use prereleases to compare template VCS
                                    tags.
    -l, --defaults                  Use default answers to questions, which
                                    might be null if not specified.
    -n, --pretend                   Run but do not make any changes
    -q, --quiet                     Suppress status output
    -r, --vcs-ref VALUE:str         Git reference to checkout in `template_src`.
                                    If you do not specify it, it will try to
                                    checkout the latest git tag, as sorted using
                                    the PEP 440 algorithm. If you want to
                                    checkout always the latest version, use
                                    `--vcs-ref=HEAD`.
    -s, --skip VALUE:str            Skip specified files if they exist already;
                                    may be given multiple times
    -w, --overwrite                 Overwrite files that already exist, without
                                    asking.
    -x, --exclude VALUE:str         A name or shell-style pattern matching files
                                    or folders that must not be copied; may be
                                    given multiple times


copier recopy 0.0.0

Recopy a subproject from its original template

The copy must have a valid answers file which contains info from the last Copier
execution, including the source template (it must be a key called `_src_path`).

This command will ignore any diff that you have generated since the last
`copier` execution. It will act as if it were the 1st time you apply the
template to the destination path. However, it will keep the answers.

If you want a smarter update that respects your project evolution, use `copier
update` instead.

Usage:
    copier recopy [SWITCHES] [destination_path=.]

Hidden-switches:
    -h, --help                      Prints this help message and quits
    --help-all                      Prints help messages of all sub-commands and
                                    quits
    -v, --version                   Prints the program's version and quits

Switches:
    -A, --skip-answered             Skip questions that have already been
                                    answered
    -T, --skip-tasks                Skip template tasks execution
    --UNSAFE, --trust               Allow templates with unsafe features (Jinja
                                    extensions, migrations, tasks)
    -a, --answers-file VALUE:str    Update using this path (relative to
                                    `destination_path`) to find the answers file
    -d, --data VARIABLE=VALUE:str   Make VARIABLE available as VALUE when
                                    rendering the template; may be given
                                    multiple times
    --data-file PATH:ExistingFile   Load data from a YAML file
    -f, --force                     Same as `--defaults --overwrite`.
    -g, --prereleases               Use prereleases to compare template VCS
                                    tags.
    -l, --defaults                  Use default answers to questions, which
                                    might be null if not specified.
    -n, --pretend                   Run but do not make any changes
    -q, --quiet                     Suppress status output
    -r, --vcs-ref VALUE:str         Git reference to checkout in `template_src`.
                                    If you do not specify it, it will try to
                                    checkout the latest git tag, as sorted using
                                    the PEP 440 algorithm. If you want to
                                    checkout always the latest version, use
                                    `--vcs-ref=HEAD`.
    -s, --skip VALUE:str            Skip specified files if they exist already;
                                    may be given multiple times
    -w, --overwrite                 Overwrite files that already exist, without
                                    asking.
    -x, --exclude VALUE:str         A name or shell-style pattern matching files
                                    or folders that must not be copied; may be
                                    given multiple times


copier update 0.0.0

Update a subproject from its original template

The copy must have a valid answers file which contains info from the last Copier
execution, including the source template (it must be a key called `_src_path`).

If that file contains also `_commit`, and `destination_path` is a git
repository, this command will do its best to respect the diff that you have
generated since the last `copier` execution. To avoid that, use `copier recopy`
instead.

Usage:
    copier update [SWITCHES] [destination_path=.]

Hidden-switches:
    -h, --help                      Prints this help message and quits
    --help-all                      Prints help messages of all sub-commands and
                                    quits
    -v, --version                   Prints the program's version and quits

Switches:
    -A, --skip-answered             Skip questions that have already been
                                    answered
    -T, --skip-tasks                Skip template tasks execution
    --UNSAFE, --trust               Allow templates with unsafe features (Jinja
                                    extensions, migrations, tasks)
    -a, --answers-file VALUE:str    Update using this path (relative to
                                    `destination_path`) to find the answers file
    -c, --context-lines VALUE:int   Lines of context to use for detecting
                                    conflicts. Increase for accuracy, decrease
                                    for resilience.; the default is 3
    -d, --data VARIABLE=VALUE:str   Make VARIABLE available as VALUE when
                                    rendering the template; may be given
                                    multiple times
    --data-file PATH:ExistingFile   Load data from a YAML file
    -g, --prereleases               Use prereleases to compare template VCS
                                    tags.
    -l, -f, --defaults              Use default answers to questions, which
                                    might be null if not specified.
    -n, --pretend                   Run but do not make any changes
    -o, --conflict VALUE:{rej, inline} Behavior on conflict: Create .rej files, or
                                    add inline conflict markers.; the default is
                                    inline
    -q, --quiet                     Suppress status output
    -r, --vcs-ref VALUE:str         Git reference to checkout in `template_src`.
                                    If you do not specify it, it will try to
                                    checkout the latest git tag, as sorted using
                                    the PEP 440 algorithm. If you want to
                                    checkout always the latest version, use
                                    `--vcs-ref=HEAD`.
    -s, --skip VALUE:str            Skip specified files if they exist already;
                                    may be given multiple times
    -x, --exclude VALUE:str         A name or shell-style pattern matching files
                                    or folders that must not be copied; may be
                                    given multiple times

CopierApp

Bases: cli.Application

The Copier CLI application.

Source code in copier/cli.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
class CopierApp(cli.Application):  # type: ignore[misc]
    """The Copier CLI application."""

    DESCRIPTION = "Create a new project from a template."
    DESCRIPTION_MORE = (
        dedent(
            """\
            Docs in https://copier.readthedocs.io/

            """
        )
        + (
            colors.yellow
            | dedent(
                """\
                WARNING! Use only trusted project templates, as they might
                execute code with the same level of access as your user.\n
                """
            )
        )
    )
    VERSION = copier_version()
    CALL_MAIN_IF_NESTED_COMMAND = False

CopierCopySubApp

Bases: _Subcommand

The copier copy subcommand.

Use this subcommand to bootstrap a new subproject from a template, or to override a preexisting subproject ignoring its history diff.

Source code in copier/cli.py 
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
@CopierApp.subcommand("copy")
class CopierCopySubApp(_Subcommand):
    """The `copier copy` subcommand.

    Use this subcommand to bootstrap a new subproject from a template, or to override
    a preexisting subproject ignoring its history diff.
    """

    DESCRIPTION = "Copy from a template source to a destination."

    cleanup_on_error = cli.Flag(
        ["-C", "--no-cleanup"],
        default=True,
        help="On error, do not delete destination if it was created by Copier.",
    )
    defaults = cli.Flag(
        ["-l", "--defaults"],
        help="Use default answers to questions, which might be null if not specified.",
    )
    force = cli.Flag(
        ["-f", "--force"],
        help="Same as `--defaults --overwrite`.",
    )
    overwrite = cli.Flag(
        ["-w", "--overwrite"],
        help="Overwrite files that already exist, without asking.",
    )

    def main(self, template_src: str, destination_path: str) -> int:
        """Call [run_copy][copier.main.Worker.run_copy].

        Params:
            template_src:
                Indicate where to get the template from.

                This can be a git URL or a local path.

            destination_path:
                Where to generate the new subproject. It must not exist or be empty.
        """

        def inner() -> None:
            with self._worker(
                template_src,
                destination_path,
                cleanup_on_error=self.cleanup_on_error,
                defaults=self.force or self.defaults,
                overwrite=self.force or self.overwrite,
            ) as worker:
                worker.run_copy()

        return _handle_exceptions(inner)

main(template_src, destination_path)

Call run_copy.

Parameters:

Name Type Description Default
template_src str

Indicate where to get the template from.

This can be a git URL or a local path.

 required
destination_path str

Where to generate the new subproject. It must not exist or be empty.

 required
Source code in copier/cli.py 
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
def main(self, template_src: str, destination_path: str) -> int:
    """Call [run_copy][copier.main.Worker.run_copy].

    Params:
        template_src:
            Indicate where to get the template from.

            This can be a git URL or a local path.

        destination_path:
            Where to generate the new subproject. It must not exist or be empty.
    """

    def inner() -> None:
        with self._worker(
            template_src,
            destination_path,
            cleanup_on_error=self.cleanup_on_error,
            defaults=self.force or self.defaults,
            overwrite=self.force or self.overwrite,
        ) as worker:
            worker.run_copy()

    return _handle_exceptions(inner)

CopierRecopySubApp

Bases: _Subcommand

The copier recopy subcommand.

Use this subcommand to update an existing subproject from a template that supports updates, ignoring any subproject evolution since the last Copier execution.

Source code in copier/cli.py 
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
@CopierApp.subcommand("recopy")
class CopierRecopySubApp(_Subcommand):
    """The `copier recopy` subcommand.

    Use this subcommand to update an existing subproject from a template that
    supports updates, ignoring any subproject evolution since the last Copier
    execution.
    """

    DESCRIPTION = "Recopy a subproject from its original template"
    DESCRIPTION_MORE = dedent(
        """\
        The copy must have a valid answers file which contains info from the
        last Copier execution, including the source template (it must be a key
        called `_src_path`).

        This command will ignore any diff that you have generated since the
        last `copier` execution. It will act as if it were the 1st time you
        apply the template to the destination path. However, it will keep the
        answers.

        If you want a smarter update that respects your project evolution, use
        `copier update` instead.
        """
    )

    defaults = cli.Flag(
        ["-l", "--defaults"],
        help="Use default answers to questions, which might be null if not specified.",
    )
    force = cli.Flag(
        ["-f", "--force"],
        help="Same as `--defaults --overwrite`.",
    )
    overwrite = cli.Flag(
        ["-w", "--overwrite"],
        help="Overwrite files that already exist, without asking.",
    )
    skip_answered = cli.Flag(
        ["-A", "--skip-answered"],
        default=False,
        help="Skip questions that have already been answered",
    )

    def main(self, destination_path: cli.ExistingDirectory = ".") -> int:
        """Call [run_recopy][copier.main.Worker.run_recopy].

        Parameters:
            destination_path:
                Only the destination path is needed to update, because the
                `src_path` comes from [the answers file][the-copier-answersyml-file].

                The subproject must exist. If not specified, the currently
                working directory is used.
        """

        def inner() -> None:
            with self._worker(
                dst_path=destination_path,
                defaults=self.force or self.defaults,
                overwrite=self.force or self.overwrite,
                skip_answered=self.skip_answered,
            ) as worker:
                worker.run_recopy()

        return _handle_exceptions(inner)

main(destination_path='.')

Call run_recopy.

Parameters:

Name Type Description Default
destination_path cli.ExistingDirectory

Only the destination path is needed to update, because the src_path comes from the answers file.

The subproject must exist. If not specified, the currently working directory is used.

 '.'
Source code in copier/cli.py 
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
def main(self, destination_path: cli.ExistingDirectory = ".") -> int:
    """Call [run_recopy][copier.main.Worker.run_recopy].

    Parameters:
        destination_path:
            Only the destination path is needed to update, because the
            `src_path` comes from [the answers file][the-copier-answersyml-file].

            The subproject must exist. If not specified, the currently
            working directory is used.
    """

    def inner() -> None:
        with self._worker(
            dst_path=destination_path,
            defaults=self.force or self.defaults,
            overwrite=self.force or self.overwrite,
            skip_answered=self.skip_answered,
        ) as worker:
            worker.run_recopy()

    return _handle_exceptions(inner)

CopierUpdateSubApp

Bases: _Subcommand

The copier update subcommand.

Use this subcommand to update an existing subproject from a template that supports updates, respecting that subproject evolution since the last Copier execution.

Source code in copier/cli.py 
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
@CopierApp.subcommand("update")
class CopierUpdateSubApp(_Subcommand):
    """The `copier update` subcommand.

    Use this subcommand to update an existing subproject from a template
    that supports updates, respecting that subproject evolution since the last
    Copier execution.
    """

    DESCRIPTION = "Update a subproject from its original template"
    DESCRIPTION_MORE = dedent(
        """\
        The copy must have a valid answers file which contains info
        from the last Copier execution, including the source template
        (it must be a key called `_src_path`).

        If that file contains also `_commit`, and `destination_path` is a git
        repository, this command will do its best to respect the diff that you have
        generated since the last `copier` execution. To avoid that, use `copier recopy`
        instead.
        """
    )

    conflict = cli.SwitchAttr(
        ["-o", "--conflict"],
        cli.Set("rej", "inline"),
        default="inline",
        help=(
            "Behavior on conflict: Create .rej files, or add inline conflict markers."
        ),
    )
    context_lines = cli.SwitchAttr(
        ["-c", "--context-lines"],
        int,
        default=3,
        help=(
            "Lines of context to use for detecting conflicts. Increase for "
            "accuracy, decrease for resilience."
        ),
    )
    defaults = cli.Flag(
        ["-l", "-f", "--defaults"],
        help="Use default answers to questions, which might be null if not specified.",
    )
    skip_answered = cli.Flag(
        ["-A", "--skip-answered"],
        default=False,
        help="Skip questions that have already been answered",
    )

    def main(self, destination_path: cli.ExistingDirectory = ".") -> int:
        """Call [run_update][copier.main.Worker.run_update].

        Parameters:
            destination_path:
                Only the destination path is needed to update, because the
                `src_path` comes from [the answers file][the-copier-answersyml-file].

                The subproject must exist. If not specified, the currently
                working directory is used.
        """

        def inner() -> None:
            with self._worker(
                dst_path=destination_path,
                conflict=self.conflict,
                context_lines=self.context_lines,
                defaults=self.defaults,
                skip_answered=self.skip_answered,
                overwrite=True,
            ) as worker:
                worker.run_update()

        return _handle_exceptions(inner)

main(destination_path='.')

Call run_update.

Parameters:

Name Type Description Default
destination_path cli.ExistingDirectory

Only the destination path is needed to update, because the src_path comes from the answers file.

The subproject must exist. If not specified, the currently working directory is used.

 '.'
Source code in copier/cli.py 
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
def main(self, destination_path: cli.ExistingDirectory = ".") -> int:
    """Call [run_update][copier.main.Worker.run_update].

    Parameters:
        destination_path:
            Only the destination path is needed to update, because the
            `src_path` comes from [the answers file][the-copier-answersyml-file].

            The subproject must exist. If not specified, the currently
            working directory is used.
    """

    def inner() -> None:
        with self._worker(
            dst_path=destination_path,
            conflict=self.conflict,
            context_lines=self.context_lines,
            defaults=self.defaults,
            skip_answered=self.skip_answered,
            overwrite=True,
        ) as worker:
            worker.run_update()

    return _handle_exceptions(inner)