Productify

Appearance

pfy sync ​

pfy sync fills project.yaml from a project that already exists on the Manager: it writes project_id and project_name, and seeds one environment alias per tenant. It never changes version or the ci: block. Use it when you join an existing project or lost your local file.

Synopsis ​

bash
pfy sync --project <slug>
pfy sync --project-id <uuid>

Description ​

The sync command pulls project metadata from the manager backend and updates your local project.yaml file. This is useful when:

  • Starting work on an existing project
  • Updating project name or ID after changes in manager
  • Recovering lost local configuration

The command preserves existing CI/CD settings (language, registry, image name) while updating project-level metadata.

Flags ​

--project <slug-or-id> ​

The slug or UUID of the project in the ProductifyFW manager; UUID-formatted values are auto-detected and looked up by ID.

bash
pfy sync --project my-application
pfy sync --project 01234567-89ab-cdef-0123-456789abcdef

--project-id <slug-or-id> (deprecated) ​

Deprecated alias of --project (it accepts the same slug-or-ID values). Use --project in new scripts.

Examples ​

Basic Sync ​

Pull project configuration from manager:

bash
pfy sync --project-id 01234567-89ab-cdef-0123-456789abcdef

Output:

Successfully synced project configuration from manager:
  ID: 01234567-89ab-cdef-0123-456789abcdef
  Name: My Application
  Environments: 2 aliases inferred from tenants

Configuration saved to project.yaml

Initialize from Manager ​

Start a new local project from existing manager project:

bash
# Clone repository
git clone https://github.com/myorg/myapp.git
cd myapp

# Initialize from manager
pfy sync --project-id 01234567-89ab-cdef-0123-456789abcdef

# Verify configuration
cat project.yaml

Result:

yaml
project_id: 01234567-89ab-cdef-0123-456789abcdef
project_name: My Application
version: 0.1.0
ci:
  type: github
  language: go
  registry: ghcr.io
  image_name: my-application

Update After Manager Changes ​

If project name changed in manager:

bash
# Before: project_name was "Old Name"
pfy sync --project my-app
# After: project_name is now "New Name"

cat project.yaml
# project_name: New Name  ← Updated
# version: 0.1.0          ← Preserved (sync never touches version)
# ci:                     ← Preserved
#   type: github          ← Preserved

Behavior ​

What Gets Updated ​

  • project_id: Set to manager project ID
  • project_name: Set to manager project name
  • environments: One alias is seeded per tenant of the project (named after the tenant slug, carrying its tenant_id), so the --env-driven deploy workflow starts pre-seeded. Existing aliases keep any extra fields (e.g. environment_id) they already carry. Only the first 100 tenants are considered; this step is best-effort and never fails the sync.

sync does not update version (see Version Management).

What Gets Preserved ​

  • ci.type: CI platform (github/gitlab)
  • ci.language: Project language (go/node)
  • ci.registry: Docker registry URL
  • ci.image_name: Docker image name

File Creation ​

If project.yaml doesn't exist, sync creates it with:

  • Project ID and name from manager
  • Default version 0.1.0
  • Default CI settings (github, go, ghcr.io)

Use Cases ​

Team Onboarding ​

New team member setting up local environment:

bash
# 1. Clone repo
git clone <repo-url>
cd project

# 2. Login to manager
pfy login --server https://manager.example.com --token <token>

# 3. Sync project config
pfy sync --project-id <project-id>

# 4. Start development
pfy ci update

Configuration Recovery ​

Lost project.yaml after git operations:

bash
# Recover from manager (creates project.yaml with default ci: settings)
pfy sync --project my-app

# Then fix the ci: block by hand if your defaults differ (pfy init refuses to run
# once project.yaml exists)
$EDITOR project.yaml

Multi-Repository Projects ​

Sync same project ID across multiple repositories:

bash
# In frontend repo
cd frontend
pfy sync --project-id 01234567-89ab-cdef-0123-456789abcdef

# In backend repo
cd ../backend
pfy sync --project-id 01234567-89ab-cdef-0123-456789abcdef

# Both repos now share project ID

Global Flags ​

--manager <url> ​

Override manager URL from config:

bash
pfy --manager https://staging-mgr.example.com sync --project-id 01234567-89ab-cdef-0123-456789abcdef

--token <string> ​

Provide authentication token:

bash
pfy --token <personal-access-token> sync --project-id 01234567-89ab-cdef-0123-456789abcdef

--verbose, -v ​

Show detailed sync progress:

bash
pfy --verbose sync --project-id 01234567-89ab-cdef-0123-456789abcdef

Output:

Connecting to ProductifyFW manager...
Fetching project details for '01234567-89ab-cdef-0123-456789abcdef'...
Successfully synced project configuration from manager:
  ID: 01234567-89ab-cdef-0123-456789abcdef
  Name: My Application
  Environments: 2 aliases inferred from tenants

Configuration saved to project.yaml

--quiet, -q ​

Suppress the progress and summary lines:

bash
pfy --quiet sync --project-id 01234567-89ab-cdef-0123-456789abcdef

Error Handling ​

Project Not Found ​

If the slug or ID does not exist, the Manager's error is passed through after the failed to fetch project from manager: prefix (the exact wording comes from the server):

bash
$ pfy sync --project no-such-project
Error: failed to fetch project from manager: ...

Solution: check the slug with pfy project list.

Authentication Required ​

If not logged in:

bash
$ pfy sync --project-id 01234567-89ab-cdef-0123-456789abcdef
Error: manager URL is required (use --manager flag, PFY_MANAGER_URL env var, or run 'pfy login')

Solution: run pfy login first.

Token rejected ​

A 401/403 from the Manager is reported as:

Error: token rejected by https://manager.example.com - either the token is invalid or expired (run 'pfy login' to replace it), or the URL points at the manager directly instead of the proxied entrypoint that injects authentication

Solution: run pfy whoami, then pfy login again, and make sure the URL is the proxied entrypoint.

Configuration Updates ​

Before sync:

yaml
# project.yaml
project_id: ""
project_name: my-local-project
version: 1.0.0
ci:
  type: github
  language: go

After pfy sync --project-id 01234567-89ab-cdef-0123-456789abcdef:

yaml
# project.yaml
project_id: 01234567-89ab-cdef-0123-456789abcdef # ← Updated
project_name: Official Name # ← Updated from manager
version: 1.0.0 # ← Preserved (sync never touches version)
ci:
  type: github # ← Preserved
  language: go # ← Preserved
environments: # ← Seeded: one alias per tenant
  prod:
    tenant_id: 33333333-4444-5555-6666-777777777777
    name: Production

Integration ​

With pfy init ​

Use sync after init to connect local project to manager:

bash
# Create local config
pfy init --name my-app

# Connect to manager project
pfy sync --project-id 01234567-89ab-cdef-0123-456789abcdef

With CI/CD ​

Use in CI to ensure config is up-to-date:

yaml
# .github/workflows/ci.yml
- name: Sync project config
  run: |
    pfy login --server $MANAGER_URL --token $MANAGER_TOKEN
    pfy sync --project-id $PROJECT_ID
    pfy ci update

With Version Management ​

Sync never touches version; the local project.yaml version is the source of truth and is managed with pfy version:

bash
pfy sync --project my-app
pfy version show   # unchanged by the sync
pfy version set --version 2.0.0

Best Practices ​

1. Sync Before Major Operations ​

Always sync before deploying or rolling out to tenants:

bash
pfy sync --project $PROJECT_SLUG
pfy application enable --app $APP_SLUG --tenant $TENANT_SLUG --project $PROJECT_SLUG

2. Commit After Sync ​

Track configuration changes:

bash
pfy sync --project my-saas
git diff project.yaml  # Review changes
git commit -am "Sync project config from manager"

3. Use in Automation ​

Add to deployment scripts:

bash
#!/bin/bash
# deploy.sh

pfy sync --project-id $PROJECT_ID
pfy version bump --part patch
pfy ci update
git commit -am "Prepare release"

4. Document Project ID ​

Store project ID in README:

markdown
# My Application

Project ID: `01234567-89ab-cdef-0123-456789abcdef`

## Setup

\`\`\`bash
pfy sync --project-id 01234567-89ab-cdef-0123-456789abcdef
\`\`\`

See Also ​