Quick Start

The first things to do with pfy: sign in to a Manager, create a project.yaml for your repository, manage its version, generate CI files, and create a project, tenant, and application on the Manager.

Prerequisites

The pfy CLI installed
The URL of a ProductifyFW Manager (the proxied entrypoint, see login)

1. Authenticate

The easiest way in is the browser login, the default when no token is supplied:

bash

pfy login --server https://manager.example.com

The CLI prints a verification URL and code, opens your browser, and mints a Personal Access Token once you approve, with no copy-paste. Verify with:

bash

pfy whoami

Alternatively, create a PAT in the Manager UI (the Personal Access Tokens page under your account settings) and save it directly:

bash

echo "$PFY_TOKEN" | pfy login --server https://manager.example.com --token-stdin

--token-stdin keeps the PAT out of ps, shell history and CI logs. You can also pass it with --token pat_AbCd1234_...; the two flags are mutually exclusive.

Either path saves your credentials to ~/.pfy/config.yaml for future commands. A token given via flags is verified against the Manager before it is saved (skip with --no-verify). See login for details.

CI / headless pipelines

Set PFY_MANAGER_URL / PFY_MANAGER_TOKEN with a PAT and skip login entirely.

2. Initialize Your Project

Initialize a new project with auto-detected configuration:

bash

# Create a new project directory
mkdir my-project && cd my-project

# Initialize with auto-detection (Go or Node.js)
pfy init --name my-project

This creates project.yaml with:

Project name
Initial version (0.1.0)
CI configuration with an auto-detected language (Go/Node.js), defaulting to GitHub Actions and ghcr.io

Example project.yaml:

yaml

project_name: my-project
version: 0.1.0
ci:
  type: github
  language: go
  registry: ghcr.io
  image_name: my-project

3. Sync from Manager (Optional)

If your project already exists in Manager, sync its configuration:

bash

pfy sync --project <slug-or-id>

This pulls project metadata (project_id, project_name) into project.yaml and seeds one environment alias per tenant of the project. It does not touch version.

4. Manage Version

Use semantic versioning for your project:

bash

# Check current version
pfy version show
# Output: 0.1.0

# Bump patch version (0.1.0 → 0.1.1)
pfy version bump

# Bump minor version (0.1.1 → 0.2.0)
pfy version bump --part minor

# Set specific version
pfy version set --version 1.0.0

5. Generate CI/CD Templates

Create CI/CD pipelines that use your project configuration:

bash

# Generate GitHub Actions workflow
pfy ci update

# Or for GitLab CI
# (detected automatically from project.yaml)
pfy ci update

This creates .github/workflows/ci.yml and .github/workflows/release.yml (or .gitlab-ci.yml) plus a Dockerfile. What the pipeline contains depends on the language in project.yaml:

Go: secret scanning, lint and tests, a deployment-drift check, and a GoReleaser release on v* tags. There is no Docker build or automatic version bump.
Node.js: the same checks plus a Docker build scanned with Trivy and, on pushes to main, an automatic patch bump of project.yaml followed by a multi-platform image push (linux/amd64, linux/arm64).

See ci for the exact jobs.

6. List Projects

View all projects in your Manager:

bash

pfy project list

Example output:

Projects:
  - My SaaS Platform (my-saas)
  - E-commerce Store (ecommerce)
2 projects

7. Create a Tenant

Add a tenant to your project:

bash

pfy tenant create \
  --project my-project \
  --slug my-tenant \
  --name "My Tenant" \
  --description "First tenant"

8. Create an Application

Applications are defined once at the project level and then enabled per tenant:

bash

# Create the application in the project
pfy application create \
  --project my-project \
  --slug my-app \
  --name "My Application" \
  --version "1.0.0" \
  --description "Production application"

# Enable it for your tenant
pfy application enable --app my-app --tenant my-tenant --project my-project

9. List Applications

View all applications in a project:

bash

pfy application list --project my-project

Common Workflows

New Project from Scratch

bash

# 1. Initialize project with auto-detection
cd my-new-project
pfy init --name my-saas

# 2. Review generated configuration
cat project.yaml

# 3. Bump version for first release
pfy version bump --part minor  # 0.1.0 → 0.2.0

# 4. Generate CI/CD pipeline
pfy ci update

# 5. Commit and push
git add project.yaml .github/workflows/ci.yml
git commit -m "Initialize project with pfy"
git push

Existing Project Setup

bash

# 1. Find your project in the Manager
pfy project list

# 2. Sync configuration
pfy sync --project <slug-or-id>

# 3. Update CI templates with synced config
pfy ci update

# 4. Verify version
pfy version show

Development to Production Workflow

Capturing IDs

List/get commands support structured output via the root -o/--output flag: pfy -o json project get --slug my-saas | jq -r .id. In text mode, pfy project get prints an ID: line by default, and list commands print each record's ID under --verbose.

bash

# 1. Initialize project
pfy init --name my-saas

# 2. Create Manager resources
pfy project create --slug my-saas --name "My SaaS Platform"

# 3. Sync Manager metadata to local config (also seeds one env alias per tenant)
pfy sync --project my-saas

# 4. Create development tenant
pfy tenant create \
  --project my-saas \
  --slug dev \
  --name "Development Environment"

# 5. Create production tenant
pfy tenant create \
  --project my-saas \
  --slug prod \
  --name "Production Environment"

# 6. Create the application once, at the project level
VERSION=$(pfy version show)
pfy application create \
  --project my-saas \
  --slug web-app \
  --name "Web Application" \
  --version $VERSION

# 7. Enable it for the dev tenant first
pfy application enable --app web-app --tenant dev --project my-saas

# 8. Bump version for release, then roll it out to production
pfy version bump --part minor
pfy application enable --app web-app --tenant prod --project my-saas
pfy application update-version --app web-app --project my-saas --version $(pfy version show)

# To carry tuned per-tenant configuration from dev to prod, copy it between
# the enablement rows (find the join IDs with `pfy application list-tenants`):
pfy application list-tenants --app web-app --project my-saas
pfy application config-copy --from <dev-t2a-id> --to <prod-t2a-id>

CI/CD with Auto-Versioning (Node.js projects)

The generated pipeline bumps the version automatically only for language: node. Go pipelines leave project.yaml alone; bump it yourself with pfy version bump.

bash

# 1. Initialize and configure
pfy init --name my-app --language node
pfy ci update

# 2. Push to main branch
git add .
git commit -m "Initial commit"
git push origin main

# 3. CI automatically:
#    - Bumps patch version (0.1.0 → 0.1.1)
#    - Commits project.yaml with [skip ci]
#    - Builds and pushes the image (my-app:0.1.1 and my-app:latest)

# 4. For feature releases, bump manually:
pfy version bump --part minor  # 0.1.1 → 0.2.0
git add project.yaml
git commit -m "Bump to v0.2.0 for new features"
git push

# CI uses the manual version (0.2.0) for the build

Using Environment Variables

Instead of flags, use environment variables:

bash

export PFY_MANAGER_URL="https://manager.example.com"
export PFY_MANAGER_TOKEN="your-token"

# Commands now use these automatically
pfy project list

Verbose Output

Get detailed information about what's happening:

bash

pfy --verbose project list

Example verbose output:

Connecting to ProductifyFW manager...
Fetching projects list...
Found 2 project(s)
Projects:
  - My SaaS Platform (my-saas)
    ID: 01234567-89ab-cdef-0123-456789abcdef
  - E-commerce Store (ecommerce)
    ID: 12345678-9abc-def0-1234-56789abcdef0
2 projects

Quiet Mode

--quiet drops headings, progress, and confirmation lines. List and get commands still print their data rows. Use it when you only care about the exit code:

bash

pfy --quiet project create --slug prod --name "Production"

For machine-readable output use -o json instead.

Next Steps

Project Configuration Guide - Deep dive into project.yaml
Version Management - Semantic versioning best practices
Auto-Versioning in CI/CD - Automated version bumps
Command Reference - All available commands
CI/CD Templates - GitHub Actions and GitLab CI setup

Getting Help

Get help for any command:

bash

# General help
pfy --help

# Command-specific help
pfy project --help
pfy project create --help

Quick Start ​

Prerequisites ​

1. Authenticate ​

2. Initialize Your Project ​

3. Sync from Manager (Optional) ​

4. Manage Version ​

5. Generate CI/CD Templates ​

6. List Projects ​

7. Create a Tenant ​

8. Create an Application ​

9. List Applications ​

Common Workflows ​

New Project from Scratch ​

Existing Project Setup ​

Development to Production Workflow ​

CI/CD with Auto-Versioning (Node.js projects) ​

Using Environment Variables ​

Verbose Output ​

Quiet Mode ​

Next Steps ​

Getting Help ​

Quick Start

Prerequisites

1. Authenticate

2. Initialize Your Project

3. Sync from Manager (Optional)

4. Manage Version

5. Generate CI/CD Templates

6. List Projects

7. Create a Tenant

8. Create an Application

9. List Applications

Common Workflows

New Project from Scratch

Existing Project Setup

Development to Production Workflow

CI/CD with Auto-Versioning (Node.js projects)

Using Environment Variables

Verbose Output

Quiet Mode

Next Steps

Getting Help