Productify

Appearance

pfy sync ​

Synchronize local project.yaml configuration with a project from the ProductifyFW manager.

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> ​

The slug of the project in the ProductifyFW manager.

bash
pfy sync --project my-application

--project-id <uuid> ​

The UUID of the project in the ProductifyFW manager. UUID-formatted values are auto-detected, so either flag works with the matching identifier.

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

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

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

sync updates only those two fields. It does not update version, and it does not populate environments — manage both by hand (see Project Configuration).

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
pfy sync --project-id 01234567-89ab-cdef-0123-456789abcdef

# Restore CI/CD settings manually or use existing values
pfy init --language go --ci-type github

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 ID '01234567-89ab-cdef-0123-456789abcdef'...
Successfully synced project configuration from manager:
  ID: 01234567-89ab-cdef-0123-456789abcdef
  Name: My Application

Configuration saved to project.yaml

--quiet, -q ​

Suppress all output except errors:

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

Error Handling ​

Project Not Found ​

If project ID doesn't exist:

bash
$ pfy sync --project-id invalid_id
Error: failed to fetch project from manager: project not found

Solution: Verify project ID in manager UI or use 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.

Permission Denied ​

If token lacks project access:

bash
$ pfy sync --project-id 01234567-89ab-cdef-0123-456789abcdef
Error: failed to fetch project from manager: forbidden

Solution: Use token with appropriate permissions or contact administrator.

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 # ← Updated from manager
ci:
  type: github # ← Preserved
  language: go # ← Preserved

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 updates the local version from the manager, so set the version after syncing if you need a different one:

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

Best Practices ​

1. Sync Before Major Operations ​

Always sync before deploying or promoting:

bash
pfy sync --project-id $PROJECT_ID
pfy application promote --application-id $APP_ID --target-tenant-id $TENANT_ID

2. Commit After Sync ​

Track configuration changes:

bash
pfy sync --project-id 01234567-89ab-cdef-0123-456789abcdef
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 ​