Productify

Appearance

pfy sync ​

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

Synopsis ​

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

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-id <string> (required) ​

The UUID of the project in the ProductifyFW manager.

bash
pfy sync --project-id proj_abc123def456

Examples ​

Basic Sync ​

Pull project configuration from manager:

bash
pfy sync --project-id proj_abc123

Output:

Successfully synced project configuration from manager:
  ID: proj_abc123
  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 proj_abc123

# Verify configuration
cat project.yaml

Result:

yaml
project_id: proj_abc123
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-id proj_abc123
# After: project_name is now "New Name"

cat project.yaml
# project_name: New Name  ← Updated
# version: 1.2.3          ← Preserved
# ci:                     ← Preserved
#   type: github          ← Preserved

Behavior ​

What Gets Updated ​

  • project_id: Set to manager project ID
  • project_name: Set to manager project name

What Gets Preserved ​

  • version: Local version number
  • ci.type: CI platform (github/gitlab)
  • ci.language: Project language (go/node)
  • ci.registry: Docker registry URL
  • ci.image_name: Docker image name
  • environments: Environment mappings

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 proj_abc123

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

# In backend repo
cd ../backend
pfy sync --project-id proj_abc123

# Both repos now share project ID

Global Flags ​

--manager <url> ​

Override manager URL from config:

bash
pfy sync --project-id proj_123 --manager https://staging-mgr.example.com

--token <string> ​

Provide authentication token:

bash
pfy sync --project-id proj_123 --token <personal-access-token>

--verbose, -v ​

Show detailed sync progress:

bash
pfy sync --project-id proj_123 --verbose

Output:

Connecting to ProductifyFW manager...
Fetching project details for ID 'proj_123'...
Successfully synced project configuration from manager:
  ID: proj_123
  Name: My Application

Configuration saved to project.yaml

--quiet, -q ​

Suppress all output except errors:

bash
pfy sync --project-id proj_123 --quiet

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 proj_123
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 proj_123
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 proj_abc123:

yaml
# project.yaml
project_id: proj_abc123 # ← Updated
project_name: Official Name # ← Updated from manager
version: 1.0.0 # ← Preserved
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 proj_123

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 doesn't affect version:

bash
pfy version set --version 2.0.0
pfy sync --project-id proj_123
pfy version show  # Still 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 proj_123
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: `proj_abc123`

## Setup

\`\`\`bash
pfy sync --project-id proj_abc123
\`\`\`

See Also ​