Quick Start - Project Actions

1

Install Project Actions

Navigate to your project directory and run the installation script:

                        $ 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:

                            $ 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

2

Verify Installation

Check that everything is working:

$ ./project --versionproject version 1.0.0+202512051802

$ ./project
                            Available commands:

                              hello   Example hello command
                        

3

Create Your First Command

Create a file called .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!"

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

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

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

  - echo: "✓ Greeting complete"

Now run your command:

$ ./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

4

Try a Real-World Example

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

# .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:

$ ./project testRun all tests

$ ./project test --unitRun unit tests only

$ ./project test --coverageRun with coverage

$ ./project test --e2eRun E2E tests

5

Docker Integration (Optional)

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

# .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
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

Quick Start Guide

Install Project Actions

Verify Installation

Create Your First Command

Try a Real-World Example

Docker Integration (Optional)

What's Next?

📚 Learn More

🎯 Key Features