# Template system structure

> Template system structure - Understanding how DataRobot organizes and configures application
> templates.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-05-06T18:17:09.553077+00:00` (UTC).

## Primary page

- [Template system structure](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html): Full documentation for this topic (HTML).

## Sections on this page

- [Overview](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#overview): In-page section heading.
- [Template repository structure](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#template-repository-structure): In-page section heading.
- [Template metadata](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#template-metadata): In-page section heading.
- [.datarobot directory](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#datarobot-directory): In-page section heading.
- [prompts.yaml](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#prompts-yaml): In-page section heading.
- [config.yaml](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#config-yaml): In-page section heading.
- [Environment configuration](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#environment-configuration): In-page section heading.
- [.env.template](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#env-template): In-page section heading.
- [.env (Generated)](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#env-generated): In-page section heading.
- [Quickstart scripts](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#quickstart-scripts): In-page section heading.
- [Naming conventions](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#naming-conventions): In-page section heading.
- [Platform requirements](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#platform-requirements): In-page section heading.
- [Unix/Linux/macOS](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#unix-linux-macos): In-page section heading.
- [Windows](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#windows): In-page section heading.
- [When to use quickstart scripts](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#when-to-use-quickstart-scripts): In-page section heading.
- [Fallback behavior](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#fallback-behavior): In-page section heading.
- [Task definitions](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#task-definitions): In-page section heading.
- [Taskfile.gen.yaml](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#taskfile-gen-yaml): In-page section heading.
- [Component taskfiles](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#component-taskfiles): In-page section heading.
- [Running tasks](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#running-tasks): In-page section heading.
- [Taskfile configuration data](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#taskfile-configuration-data): In-page section heading.
- [Multi-level configuration](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#multi-level-configuration): In-page section heading.
- [Discovery order](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#discovery-order): In-page section heading.
- [Example: backend prompts](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#example-backend-prompts): In-page section heading.
- [Example: frontend prompts](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#example-frontend-prompts): In-page section heading.
- [Template lifecycle](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#template-lifecycle): In-page section heading.
- [1. Discovery](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#discovery): In-page section heading.
- [2. Cloning](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#cloning): In-page section heading.
- [3. Configuration](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#configuration): In-page section heading.
- [4. Development](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#development): In-page section heading.
- [5. Deployment](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#deployment): In-page section heading.
- [Template types](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#template-types): In-page section heading.
- [Python templates](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#python-templates): In-page section heading.
- [Key features](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#key-features): In-page section heading.
- [Node.js templates](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#nodejs-templates): In-page section heading.
- [Multi-language templates](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#multi-language-templates): In-page section heading.
- [Best practices](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#best-practices): In-page section heading.
- [Version control](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#version-control): In-page section heading.
- [Documentation](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#documentation): In-page section heading.
- [Sensible defaults](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#sensible-defaults): In-page section heading.
- [Clear prompts](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#clear-prompts): In-page section heading.
- [5. Organized structure](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#organized-structure): In-page section heading.
- [Template updates](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#template-updates): In-page section heading.
- [Checking for updates](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#checking-for-updates): In-page section heading.
- [Updating templates](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#updating-templates): In-page section heading.
- [Creating your own template](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#creating-your-own-template): In-page section heading.
- [1. Start with base structure](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#start-with-base-structure): In-page section heading.
- [2. Add template files](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#add-template-files): In-page section heading.
- [3. Define prompts](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#define-prompts): In-page section heading.
- [4. Create an environment template](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#create-an-environment-template): In-page section heading.
- [5. Define tasks](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#define-tasks): In-page section heading.
- [6. Configure Taskfile data](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#configure-taskfile-data): In-page section heading.
- [7. Test the template](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#test-the-template): In-page section heading.
- [8. Publish the template](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#publish-the-template): In-page section heading.
- [See also](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/structure.html#see-also): In-page section heading.

## Related documentation

- [Agentic AI](https://docs.datarobot.com/en/docs/agentic-ai/index.html): Linked from this page.
- [CLI](https://docs.datarobot.com/en/docs/agentic-ai/cli/index.html): Linked from this page.
- [Template system](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/index.html): Linked from this page.
- [Interactive configuration](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/interactive-config.html): Linked from this page.
- [dr task compose documentation](https://docs.datarobot.com/en/docs/agentic-ai/cli/commands/task.html#taskfile-data-configuration): Linked from this page.
- [Environment variables](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html): Linked from this page.
- [dr run](https://docs.datarobot.com/en/docs/agentic-ai/cli/commands/run.html): Linked from this page.
- [Command reference: templates](https://docs.datarobot.com/en/docs/agentic-ai/cli/commands/templates.html): Linked from this page.

## Documentation content

This page provides an understanding of how DataRobot organizes and configures application templates.

## Overview

DataRobot templates are Git repositories that contain application code, configuration, and metadata to deploy custom applications to DataRobot. The CLI provides tools to clone, configure, and manage these templates.

## Template repository structure

A typical template repository:

```
my-datarobot-template/
├── .datarobot/              # Template metadata
│   ├── prompts.yaml         # Configuration prompts
│   ├── config.yaml          # Template settings
│   └── cli/                 # CLI-specific files
│       └── bin/             # Quickstart scripts
│           └── quickstart.sh
├── .env.template            # Environment variable template
├── .taskfile-data.yaml      # Taskfile configuration (optional)
├── .gitignore
├── README.md
├── Taskfile.gen.yaml        # Generated task definitions
├── src/                     # Application source code
│   ├── app/
│   │   └── main.py
│   └── tests/
├── requirements.txt         # Python dependencies
└── package.json             # Node dependencies (if applicable)
```

## Template metadata

### .datarobot directory

The `.datarobot` directory contains template-specific configuration:

```
.datarobot/
├── prompts.yaml        # User prompts for setup wizard
├── config.yaml         # Template metadata
└── README.md          # Template-specific docs
```

### prompts.yaml

Defines interactive configuration prompts. See [Interactive configuration](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/interactive-config.html) for more details.

Review the example prompt yaml configuration below.

```
prompts:
  - key: "app_name"
    env: "APP_NAME"
    help: "Enter your application name"
    default: "my-app"
    optional: false

  - key: "deployment_target"
    env: "DEPLOYMENT_TARGET"
    help: "Select deployment target"
    options:
      - name: "Development"
        value: "dev"
      - name: "Production"
        value: "prod"
```

### config.yaml

Template metadata and settings:

```
name: "My DataRobot Template"
version: "1.0.0"
description: "A sample DataRobot application template"
author: "DataRobot"
repository: "https://github.com/datarobot/template-example"

# Minimum CLI version required
min_cli_version: "0.1.0"

# Tags for discovery
tags:
  - python
  - streamlit
  - machine-learning

# Required DataRobot features
requirements:
  features:
    - custom_applications
  permissions:
    - CREATE_CUSTOM_APPLICATION
```

## Environment configuration

### .env.template

Review a template for environment variables. Note that the commented lines are optional.

```
# Required configuration
APP_NAME=
DATAROBOT_ENDPOINT=

# Optional configuration (commented out by default)
# DEBUG=false
# LOG_LEVEL=info

# Database configuration (conditional)
# DATABASE_URL=postgresql://localhost:5432/mydb
# DATABASE_POOL_SIZE=10

# Authentication
# AUTH_ENABLED=false
# AUTH_PROVIDER=oauth2
```

### .env (Generated)

Created by the CLI during setup, the `.env` file contains actual values. Note that `.env` should be in `.gitignore` and never committed.

```
# Required configuration
APP_NAME=my-awesome-app
DATAROBOT_ENDPOINT=https://app.datarobot.com

# Optional configuration
DEBUG=true
LOG_LEVEL=debug

# Database configuration
DATABASE_URL=postgresql://localhost:5432/mydb
DATABASE_POOL_SIZE=5
```

## Quickstart scripts

Templates can optionally provide quickstart scripts to automate application initialization. These scripts are executed by the `dr start` command.

Quickstart scripts must be placed in `.datarobot/cli/bin/`.

### Naming conventions

Scripts must start with `quickstart` (case-sensitive):

- ✅ quickstart
- ✅ quickstart.sh
- ✅ quickstart.py
- ✅ quickstart-dev
- ❌ Quickstart.sh (wrong casing)
- ❌ start.sh (wrong name)

If there are multiple scripts matching the pattern, the first one found in lexicographical order will be executed.

### Platform requirements

Review the requirements for different platforms below.

#### Unix/Linux/macOS

- Must have executable permissions ( chmod +x )
- Can be any executable file (shell script, Python script, compiled binary, etc.)

#### Windows

- Must have an executable extension: .exe , .bat , .cmd , or .ps1

### When to use quickstart scripts

Quickstart scripts are useful for:

- Multi-step initialization: When your application requires several setup steps
- Dependency management: Install packages or tools before starting
- Environment validation: Check prerequisites before launch
- Custom workflows: Template-specific initialization logic

### Fallback behavior

If `dr start` does not find a quickstart, it automatically launches the interactive `dr templates setup` wizard instead to ensure that you can always get started even without a custom script.

## Task definitions

### Taskfile.gen.yaml

The CLI automatically generates `Taskfile.gen.yaml` to aggregate component tasks. This file includes a `dotenv` directive to load environment variables from `.env`.

Important: Component taskfiles cannot have their own `dotenv` directives. The CLI detects conflicts and prevents generation if a component taskfile already has a `dotenv` declaration.

The generated structure is shown below.

```
version: '3'

dotenv: [".env"]

includes:
  backend:
    taskfile: ./backend/Taskfile.yaml
    dir: ./backend
  frontend:
    taskfile: ./frontend/Taskfile.yaml
    dir: ./frontend
```

### Component taskfiles

Component directories define their own tasks:

Review the structure of `backend/Taskfile.yaml` below.

```
version: '3'

# Note: No dotenv directive are allowed here

tasks:
  dev:
    desc: Start development server
    cmds:
      - python -m uvicorn src.app.main:app --reload

  test:
    desc: Run tests
    cmds:
      - pytest src/tests/

  build:
    desc: Build application
    cmds:
      - docker build -t {{.APP_NAME}} .
```

### Running tasks

The `dr run` command requires a `.env` file to be present:

```
# List all available tasks
dr run --list

# Run a specific task
dr run dev

# Run multiple tasks
dr run lint test

# Run tasks in parallel
dr run lint test --parallel
```

If you're not in a DataRobot template directory (no `.env` file), you'll see the following message:

```
You don't seem to be in a DataRobot Template directory.
This command requires a .env file to be present.
```

### Taskfile configuration data

Template authors can optionally provide a `.taskfile-data.yaml` file to configure the generated Taskfile. This file allows specifying port numbers for development servers and other configuration data.

See [dr task compose documentation](https://docs.datarobot.com/en/docs/agentic-ai/cli/commands/task.html#taskfile-data-configuration) for complete details on the file format and usage.

## Multi-level configuration

Templates can have nested `.datarobot` directories for component-specific configuration:

```
my-template/
├── .datarobot/
│   └── prompts.yaml          # Root level prompts
├── backend/
│   ├── .datarobot/
│   │   └── prompts.yaml      # Backend prompts
│   └── src/
├── frontend/
│   ├── .datarobot/
│   │   └── prompts.yaml      # Frontend prompts
│   └── src/
└── .env.template
```

### Discovery order

The CLI discovers prompts in this order:

1. Root .datarobot/prompts.yaml
2. Subdirectory prompts (depth-first search, up to depth 2)
3. Merged and deduplicated

### Example: backend prompts

`backend/.datarobot/prompts.yaml`:

```
prompts:
  - key: "api_port"
    env: "API_PORT"
    help: "Backend API port"
    default: "8000"
    section: "backend"

  - key: "database_url"
    env: "DATABASE_URL"
    help: "Database connection string"
    section: "backend"
```

### Example: frontend prompts

`frontend/.datarobot/prompts.yaml`:

```
prompts:
  - key: "ui_port"
    env: "UI_PORT"
    help: "Frontend UI port"
    default: "3000"
    section: "frontend"

  - key: "api_endpoint"
    env: "API_ENDPOINT"
    help: "Backend API endpoint"
    default: "http://localhost:8000"
    section: "frontend"
```

## Template lifecycle

### 1. Discovery

Templates are discovered from DataRobot:

```
# List available templates
dr templates list
```

Output:

```
Available templates:
* python-streamlit     - Streamlit application template
* react-frontend       - React frontend template
* fastapi-backend      - FastAPI backend template
```

### 2. Cloning

Clone a template to your local machine:

```
# Clone a specific template
dr templates clone python-streamlit

# Clone to a custom directory
dr templates clone python-streamlit my-app
```

This:
- Clones the Git repository
- Sets up directory structure
- Initializes configuration files

### 3. Configuration

Configure the template interactively:

```
# Full setup wizard
dr templates setup

# Or configure existing template
cd my-template
dr dotenv setup
```

### 4. Development

Work on your application:

```
# Run development server (requires .env file)
dr run dev

# Run tests
dr run test

# Build for deployment
dr run build
```

Note: All `dr run` commands require a `.env` file in the current directory. If you see an error about not being in a template directory, run `dr dotenv setup` to create your `.env` file.

### 5. Deployment

Deploy to DataRobot:

```
dr run deploy
```

## Template types

### Python templates

```
python-template/
├── .datarobot/
├── requirements.txt
├── setup.py
├── src/
│   └── app/
│       └── main.py
├── tests/
└── .env.template
```

#### Key features

- Python dependencies in requirements.txt
- Source code in src/
- Tests in tests/

### Node.js templates

```
node-template/
├── .datarobot/
├── package.json
├── src/
│   └── index.js
├── tests/
└── .env.template
```

#### Key features

- Node dependencies in package.json
- Source code in src/
- npm scripts integration

### Multi-language templates

```
full-stack-template/
├── .datarobot/
├── backend/
│   ├── .datarobot/
│   ├── requirements.txt
│   └── src/
├── frontend/
│   ├── .datarobot/
│   ├── package.json
│   └── src/
├── docker-compose.yml
└── .env.template
```

#### Key features

- Separate backend and frontend
- Component-specific configuration
- Docker composition

## Best practices

### Version control

Note: Always exclude `.env` and `Taskfile.gen.yaml` from version control. The CLI generates `Taskfile.gen.yaml` automatically.

```
# .gitignore should include:
.env
Taskfile.gen.yaml
*.log
__pycache__/
node_modules/
dist/
```

### Documentation

Include a clear README.

```
# My template

## Quick start {: #quick-start }

1. Clone: `dr templates clone my-template`
2. Configure: `dr templates setup`
3. Run: `dr run dev`

## Available tasks {: #available-tasks }

- `dr run dev`: development server.
- `dr run test`: run tests.
- `dr run build`: build for production.
```

### Sensible defaults

Provide defaults in `.env.template`.

```
# Good defaults for local development
API_PORT=8000
DEBUG=true
LOG_LEVEL=info
```

### Clear prompts

Use descriptive help text.

```
prompts:
  - key: "database_url"
    help: "PostgreSQL connection string (format: postgresql://user:pass@host:5432/dbname)"
```

### 5. Organized structure

Keep related files together.

```
src/
├── api/          # API endpoints
├── models/       # Data models
├── services/     # Business logic
└── utils/        # Utilities
```

## Template updates

### Checking for updates

```
# Check current template status
dr templates status

# Shows:
# - Current version
# - Latest available version
# - Modified files
# - Available updates
```

### Updating templates

```
# Update to latest version
git pull origin main

# Re-run configuration if needed
dr dotenv setup
```

## Creating your own template

### 1. Start with base structure

```
mkdir my-new-template
cd my-new-template
git init
```

### 2. Add template files

Create the necessary files:

```
# Configuration
mkdir .datarobot
touch .datarobot/prompts.yaml
touch .env.template

# Application structure
mkdir -p src/app
touch src/app/main.py

# Tasks
touch Taskfile.gen.yaml
```

### 3. Define prompts

`.datarobot/prompts.yaml`:

```
prompts:
  - key: "app_name"
    env: "APP_NAME"
    help: "Enter your application name"
    optional: false
```

### 4. Create an environment template

`.env.template`:

```
APP_NAME=
DATAROBOT_ENDPOINT=
```

### 5. Define tasks

Create component Taskfiles (e.g., `backend/Taskfile.yaml`):

```
version: '3'

tasks:
  dev:
    desc: Start development server
    cmds:
      - echo "Starting {{.APP_NAME}}"
```

### 6. Configure Taskfile data

Optional. Create `.taskfile-data.yaml` to provide additional configuration for the generated root taskfile:

```
# .taskfile-data.yaml
# Optional configuration for dr task compose

# Ports to display when running dev task
ports:
  - name: Backend
    port: 8080
  - name: Frontend
    port: 5173
```

This allows developers using your template to see which ports services run on when they execute `task dev`.

### 7. Test the template

```
# Test the setup locally
dr templates setup

# Verify configuration
dr run --list
```

### 8. Publish the template

```
# Push to GitHub
git add .
git commit -m "Initial template"
git push origin main

# Register with DataRobot (contact your admin)
```

## See also

- Interactive configuration : Configuration wizard details.
- Environment variables : Manage .env files.
- dr run : Task execution.
- dr task compose : Taskfile composition and configuration.
- Command reference: templates : Template commands.