Productify

Appearance

Quick Start ​

Get started with the pfy CLI in minutes.

Prerequisites ​

1. Authenticate ​

Create a Personal Access Token in the Manager UI (Settings → Personal Access Tokens), then save it together with your Manager URL. Both flags are required:

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 directly with --token pat_AbCd1234_... — the two flags are mutually exclusive, and exactly one is required.

This saves your credentials to ~/.pfy/config.yaml for future commands. The token is not verified at login time — a bad token only surfaces on the next authenticated command. See login for details.

Not yet implemented

There is no browser sign-in flow: pfy login cannot provision a token for you — you must issue a PAT in the Manager UI first. A browser single sign-on flow is planned — see Known Issues.

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-id <project-id>

This pulls project metadata and updates project.yaml automatically.

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, with:

  • Docker build using the version from project.yaml
  • Auto-versioning on main branch pushes
  • Multi-platform builds (linux/amd64, linux/arm64)

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)

7. Create a Tenant ​

Add a tenant to your project:

bash
# First, get the project ID
pfy project get --slug my-project

# Create the tenant using the project ID
pfy tenant create \
  --project-id <project-id> \
  --slug my-tenant \
  --name "My Tenant" \
  --description "First tenant"

8. Create an Application ​

Deploy an application for your tenant:

bash
# Get the tenant ID
pfy tenant list --project my-project

# Create the application
pfy application create \
  --tenant-id <tenant-id> \
  --slug my-app \
  --name "My Application" \
  --version "1.0.0" \
  --description "Production application"

9. List Applications ​

View all applications in a tenant:

bash
pfy application list --tenant my-tenant

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. Get project ID from Manager
pfy project list

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

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

# 4. Verify version
pfy version show

Development to Production Workflow ​

Capturing IDs

There is no -o json flag — the CLI prints human-readable text only (see Known Issues). To capture an ID you must parse that text: pfy project get prints an ID: line by default, and list commands print each record's ID only 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"
PROJECT_ID=$(pfy project get --slug my-saas | awk '/^ID:/ {print $2}')

# 3. Sync Manager metadata to local config
pfy sync --project-id $PROJECT_ID

# 4. Create development tenant
pfy tenant create \
  --project-id $PROJECT_ID \
  --slug dev \
  --name "Development Environment"

# 5. Create production tenant
pfy tenant create \
  --project-id $PROJECT_ID \
  --slug prod \
  --name "Production Environment"

# 6. Create application in dev using project version
#    --verbose prints an "ID:" line under each tenant; take the one after "(dev)"
DEV_TENANT_ID=$(pfy --verbose tenant list --project my-saas | awk '/\(dev\)$/ {getline; print $2}')
VERSION=$(pfy version show)
pfy application create \
  --tenant-id $DEV_TENANT_ID \
  --slug web-app \
  --name "Web Application" \
  --version $VERSION

# 7. Bump version for release
pfy version bump --part minor

# 8. Promote to production with new version
APP_ID=$(pfy --verbose application list --tenant dev | awk '/\(web-app\)/ {getline; print $2}')
PROD_TENANT_ID=$(pfy --verbose tenant list --project my-saas | awk '/\(prod\)$/ {getline; print $2}')
pfy application promote \
  --application-id $APP_ID \
  --target-tenant-id $PROD_TENANT_ID \
  --slug web-app
  # --slug is required; uses version from project.yaml automatically

CI/CD with Auto-Versioning ​

bash
# 1. Initialize and configure
pfy init --name my-app
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)
#    - Builds Docker image (my-app:0.1.1)
#    - Commits version change with [skip ci]

# 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

Quiet Mode ​

Minimize output for scripting:

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

Next Steps ​

Getting Help ​

Get help for any command:

bash
# General help
pfy --help

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