Quick Start — Project Actions

Install Project Actions

Navigate to your project directory and run the installation script:

Terminal

$ cd /path/to/your/project
$ curl -fsSL https://project-actions.org/install.sh | bash

With Starter Commands: Add --with-starter-commands to get example commands:

Terminal

$ curl -fsSL https://project-actions.org/install.sh | bash -s -- --with-starter-commands

This will create:

.project/ directory for your commands
project executable wrapper script
.project/.runtime/ directory for the runner

Verify Installation

Check that everything is working:

Terminal

$ ./project --version
project version 1.0.0+202512051802

Terminal

$ ./project
Available commands:
  hello    Example hello command

Create Your First Command

Create a file called .project/greet.yaml:

.project/greet.yaml

# .project/greet.yaml
help:
  short: Greet the user
  long: |
    This command greets the user and displays some project information.
    Pass --formal for a formal greeting.
  order: 10

steps:
  - echo: "Hello from Project Actions!"  # primitive

  - if-option: formal
    then:
      - echo: "Good day to you, esteemed developer."

  - if-no-option: formal
    then:
      - echo: "Hey there! 👋"

  - run: "echo 'Project directory:' && pwd"  # primitive

  - echo: "✓ Greeting complete"

Now run your command:

Terminal

$ ./project greet
Hello from Project Actions!
Hey there! 👋
Project directory: /path/to/project
✓ Greeting complete

$ ./project greet --formal
Hello from Project Actions!
Good day to you, esteemed developer.
Project directory: /path/to/project
✓ Greeting complete

Try a Real-World Example

Let's create a practical test command that handles different testing scenarios:

.project/test.yaml

# .project/test.yaml
help:
  short: Run tests
  long: |
    Run the test suite.

    Options:
      --watch      Watch for changes
      --coverage   Generate coverage report
      --unit       Run only unit tests
      --e2e        Run only E2E tests
  order: 30

steps:
  - echo: "🧪 Running tests..."

  - check-for: npm
    if-missing: "Node.js is required but not installed"

  - if-missing: node_modules
    then:
      - echo: "Installing dependencies..."
      - run: "npm install"

  - if-option: unit
    then:
      - run: "npm run test:unit"

  - if-option: e2e
    then:
      - run: "npm run test:e2e"

  - if-no-option: unit|e2e
    then:
      - run: "npm test"

  - if-option: coverage
    then:
      - run: "npm run test:coverage"
      - echo: "Coverage report: ./coverage/index.html"

  - echo: "✅ Tests complete"

Now you can run tests with various options:

Terminal

$ ./project test
Run all tests

Terminal

$ ./project test --unit
Run unit tests only

Terminal

$ ./project test --coverage
Run with coverage

Terminal

$ ./project test --e2e
Run E2E tests

Docker Integration (Optional)

If you're using Docker Compose, Project Actions can manage your containers:

.project/up.yaml

# .project/up.yaml
help:
  short: Start the project
  order: 10

context: outside-container

steps:
  - check-for: docker
    if-missing: "Docker is required. Install from https://docker.com"

  - action: compose-up

  - echo: |
      ✅ Project is up and running!
      → Web: http://localhost:8000

.project/console.yaml

# .project/console.yaml
help:
  short: Open a shell in the web container
  order: 50

context: outside-container

steps:
  - action: compose-exec
    service: web
    command: /bin/bash
    interactive: true

Up and running in 5 minutes

Install Project Actions

Verify Installation

Create Your First Command

Try a Real-World Example

Docker Integration (Optional)

What's Next?

📦 Expand Your Project

📚 Learn More