---
title: "new"
description: "catcli new — create a project from a template, or list the templates."
url: "https://docs.justcat.it/reference/cat-cli/new/"
---
# new


## Synopsis

```
catcli new --list [-o] [-l <level>] [-q]
catcli new [-t <code>] [-n <name>] [-d <directory>] [-c] [-w] [-f] [-o] [-l <level>] [-q]
```

## Options

| Short | Long | Value | Meaning |
|-------|------|-------|---------|
| | `--list` | | List the templates and stop. No short form (`-l` is `--loggingLevel`). Combines only with `-o`, `-l`, `-q`. |
| `-t` | `--template` | code | Template to create the project from. Default: `default`. |
| `-n` | `--name` | name | Name of the project; becomes the project file name (`.cat.yaml` is appended when missing) and, with `-w`, the folder name. Default: `TestMyData`. Use letters and digits. |
| `-d` | `--directory` | path | Where to create the files. Must exist. Default: the current directory. |
| `-c` | `--commented` | | Use the commented variant of the template's project file — every setting explained inline. Without it the project file is kept lean. |
| `-w` | `--wrap` | | Create a sub-folder named after the project inside `-d` and put everything there, instead of writing straight into `-d`. |
| `-f` | `--force` | | **Delete everything in the target folder first.** The target is `-d` itself unless `-w` is given, so `-f` without `-w` empties the directory you point it at. |
| `-o` | `--online` | | With `--list`: list the templates on the CAT server instead of the local ones. When creating: first fetch the template from the server if a newer version exists there. Without `-o`, CAT never goes online. |
| `-l` | `--loggingLevel` | level | `Error` (default), `None`, `Information`, `Debug`, … — see [Logging](https://docs.justcat.it/reference/cat-cli/introduction/#logging "Logging"). |
| `-q` | `--quiet` | | Hide the "working offline" notice. |

## What it does

Copies the template's files into the target folder, keeps the plain or the commented project file according to `-c`, renames it to `<name>.cat.yaml` and replaces the project-name placeholder in every file. Two templates ship with CAT CLI:

| Code | Template | Content |
|------|----------|---------|
| `default` | Default template | One simple test against a local SQL Server database. The starting point for a real project. |
| `getStartedWindows` | Get started (for MS Windows users) | A few tests over two sample CSV files, with a read-me and a run script — the project the [Get started tutorial](https://docs.justcat.it/get-started/cat-cli/explore/ "Explore sample project") walks through. |

`--list --online` may show more, and newer versions of these two. A template fetched with `-o` is stored under `%APPDATA%\CAT\Templates\Projects\` and used from there afterwards, online or not; creating a project always works from the local copy.

`new` runs the sign-in and plan check like `run` does, even though it touches no data.

## Output

`--list` prints a table — `Code`, `Template Name`, `Description`, `Version`. Creating a project prints nothing at the default logging level; `-l Information` shows the target folder and each step.

## Exit code

`0` when the project was created or the list printed. `1` when the template code is unknown or the `-d` directory does not exist (the message says which). `2`–`7` from the sign-in and plan check — see [Exit codes](https://docs.justcat.it/reference/cat-cli/introduction/#exit-codes "Exit codes").

## Examples

```
# what templates are there, locally and on the server
catcli new --list
catcli new --list -o

# a lean project file named TestMyData.cat.yaml in the current directory
catcli new

# a project of your own: Dwh.cat.yaml in a new folder D:\Testing\Dwh, with inline comments
catcli new -t default -n Dwh -d "D:\Testing" -w -c

# the tutorial sample, refreshed from the server, in its own folder
catcli new -t getStartedWindows -n CatSampleProject -d "%USERPROFILE%\Documents\CAT" -w -o

# start the sample over: empties D:\Samples\CatSampleProject first
catcli new -t getStartedWindows -n CatSampleProject -d "D:\Samples" -w -f
```

## Related

- [Introduction](https://docs.justcat.it/reference/cat-cli/introduction/ "Introduction") — conventions, sign-in, exit codes.
- [Project file](https://docs.justcat.it/reference/project-file/ "Project file") — what the generated file contains and how to grow it.
- [Get started with CAT CLI](https://docs.justcat.it/get-started/cat-cli/ "Get started with CAT CLI") — the tutorial built on `getStartedWindows`.
- [How to create a project file](https://docs.justcat.it/how-to-guides/organize-and-run-tests/how-to-create-project-file/ "How to create a project file").