Getting Started

Quick Start

Build and deploy your first CliFi workflow in under five minutes. This guide walks you through initializing a project, defining a workflow, and running it locally.

Prerequisites

• CliFi 2.0 or later (installation guide)
• Node.js 18 or later
• Git
• Docker (optional, for containerized tasks)

Step 1 - Initialize a project

Create a new directory and initialize CliFi. This creates a clifi.yaml configuration file and a .clifi directory for state and cache:

mkdir hello-clifi && cd hello-clifi
clifi init

You will see output like:

Created clifi.yaml
Created .clifi/
Created .clifi/.gitignore
Project initialized successfully.

Step 2 - Explore the configuration

Open clifi.yaml. The generated file contains a simple workflow with two tasks - one that builds an artifact and one that validates it:

version: "2.0"
name: hello-clifi

tasks:
  build:
    description: "Build the application"
    runner: shell
    command: |
      echo "Building application..."
      mkdir -p dist
      echo 'Hello from CliFi!' > dist/output.txt

  test:
    description: "Run validation"
    runner: shell
    dependsOn: [build]
    command: |
      echo "Running tests..."
      cat dist/output.txt
      echo "All tests passed!"

Step 3 - Run the workflow

Execute the workflow with clifi run. CliFi automatically detects the task graph, runs build first, then test:

clifi run

Expected output:

[build] Building application...
[build] Done in 0.12s
[test] Running tests...
[test] Hello from CliFi!
[test] All tests passed!
[test] Done in 0.08s

Workflow completed successfully in 0.23s

Step 4 - Add environment configuration

Real projects have multiple environments. Create an environments directory with staging and production overrides:

mkdir environments

cat > environments/staging.yaml << 'EOF'
variables:
  API_URL: https://api.staging.example.com
  LOG_LEVEL: debug
EOF

cat > environments/production.yaml << 'EOF'
variables:
  API_URL: https://api.example.com
  LOG_LEVEL: info
EOF

Reference these variables in your workflow:

  deploy:
    description: "Deploy to target environment"
    runner: shell
    dependsOn: [test]
    command: |
      echo "Deploying to ${{ env.API_URL }}"
      echo "Log level: ${{ env.LOG_LEVEL }}"

Step 5 - Run with an environment

Specify the environment with the --env flag:

clifi run --env staging

CliFi loads the staging variables and injects them into your tasks. The output now shows the staging URL:

[deploy] Deploying to https://api.staging.example.com
[deploy] Log level: debug

Step 6 - Enable caching

CliFi caches task outputs by default, but you can control caching behavior per task. Add cache configuration to skip rebuilds when inputs have not changed:

  build:
    description: "Build the application"
    runner: shell
    cache:
      key: "{{ hashFiles('src/**') }}"
      paths: [dist/]
    command: |
      echo "Building application..."
      mkdir -p dist
      echo 'Hello from CliFi!' > dist/output.txt

Run again and notice the cache hit:

clifi run
# [build] Cache hit - restoring from previous run
# [build] Done in 1.45s (restored)

Step 7 - List available tasks

As your workflow grows, use the tasks command to see all defined tasks and their dependencies:

clifi tasks

What is next?

You now have a working CliFi project. From here, explore the CLI reference to learn about advanced flags, or dive into the guides for CI/CD integration and Docker workflows.