login

Authenticate with the ProductifyFW Manager.

Not yet implemented

pfy login takes a manually-issued PAT. The browser single sign-on flow, pfy whoami, pfy logout, and the --web/--no-web flags described in Planned: Browser Single Sign-On do not exist yet — see Known Issues.

Synopsis

pfy login --server <url> --token-stdin      # recommended
pfy login --server <url> --token <token>

Description

The login command saves your ProductifyFW Manager URL and a Personal Access Token (PAT) to ~/.pfy/config.yaml. --server is required, and the PAT must be supplied by exactly one of --token-stdin or --token; there is no browser flow and no interactive prompt. The token is not verified against the Manager at login time — a mistyped or expired token only surfaces the next time you run an authenticated command.

--server must point at the proxied entrypoint, not the Manager directly: the Manager only accepts PAT traffic carrying the X-Token-* headers the proxy injects, so a direct URL yields a 401 regardless of the token. Do not include the /query path; it is appended automatically.

Flags

Flag	Aliases	Required	Description
--server		Yes	ProductifyFW Manager URL (http(s)😕/host:port) — the proxied entrypoint
--token-stdin		One of	Read the PAT from stdin, keeping it out of ps, shell history and CI logs
--token	--pat	One of	Personal Access Token, passed on the command line

--token and --token-stdin are mutually exclusive, and exactly one is required:

$ echo $TOKEN | pfy login --server https://manager.example.com --token-stdin --token pat_x
Error: --token and --token-stdin are mutually exclusive: pass the token on the command line or on stdin, not both

$ pfy login --server https://manager.example.com
Error: a Personal Access Token is required: pipe it in with --token-stdin (recommended - keeps it out of 'ps', shell history and CI logs) or pass --token

Examples

Save a PAT from stdin (recommended)

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

Output:

Successfully logged in to ProductifyFW manager at: https://manager.example.com
Configuration saved to ~/.pfy/config.yaml

Surrounding whitespace is trimmed, so the trailing newline from echo is not saved as part of the secret. If stdin is empty, login fails rather than saving a blank token:

$ printf "" | pfy login --server https://manager.example.com --token-stdin
Error: --token-stdin was given but stdin was empty

Save a PAT on the command line

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

Avoid --token on shared machines

A token passed as --token <value> is visible in ps output and shell history. Prefer --token-stdin. In CI, you can also set PFY_MANAGER_TOKEN and skip login entirely (see CI/CD Authentication).

Configuration File

The login command creates or updates ~/.pfy/config.yaml:

manager_url: https://manager.example.com
token: your-personal-access-token

File Location

• Default: ~/.pfy/config.yaml
• Permissions: Automatically set to 0600 (read/write for owner only)

Manual Configuration

You can also manually create the configuration file:

mkdir -p ~/.pfy
cat > ~/.pfy/config.yaml <<EOF
manager_url: https://manager.example.com
token: your-personal-access-token
EOF
chmod 600 ~/.pfy/config.yaml

Personal Access Tokens

Create one manually in the Manager web interface:

1. Log in to the ProductifyFW Manager web interface
2. Navigate to Settings → Personal Access Tokens
3. Click Create Token
4. Provide a descriptive name (e.g., "CI - release pipeline")
5. Optionally set an expiration date
6. Copy the token immediately (it won't be shown again)

Token Security

Best Practices:

• Store the PAT via PFY_MANAGER_TOKEN rather than pasting it into shell history
• Rotate tokens regularly; revoke tokens for machines you no longer use
• Never commit tokens to version control
• Review your PAT list (name + last used) periodically

Multiple Environments

Development and Production

Manage multiple Manager instances:

# Login to development
pfy login --server https://dev.manager.example.com --token dev-token

# Later, override for production commands
pfy --manager https://prod.manager.example.com \
    --token prod-token \
    project list

Environment-Specific Aliases

The CLI always reads ~/.pfy/config.yaml; there is no flag to point it at another config file. To target multiple environments, use shell aliases with the --manager and --token overrides:

# ~/.bashrc or ~/.zshrc
alias pfy-dev='pfy --manager https://dev.manager.example.com --token dev-token'
alias pfy-prod='pfy --manager https://prod.manager.example.com --token prod-token'

pfy-dev project list
pfy-prod project list

Verification

Test Authentication

There is no pfy whoami yet (see Planned). Verify by running an authenticated command:

# List projects (requires authentication) - fails if the server/token is wrong
pfy project list

If it succeeds, authentication is working.

View Current Configuration

cat ~/.pfy/config.yaml

Switching Accounts

Run pfy login again with a different --server/--token — it overwrites the previous configuration file. Revoke the old PAT from the Manager's PAT list if you're done with it.

Logout

Not yet implemented

There is no pfy logout command yet.

To remove saved credentials today, delete the configuration file directly:

rm ~/.pfy/config.yaml

The PAT itself stays valid until revoked in the Manager (or until it expires).

CI/CD Authentication

Using Environment Variables

In CI/CD pipelines, use environment variables instead of login:

# Set environment variables
export PFY_MANAGER_URL="https://manager.example.com"
export PFY_MANAGER_TOKEN="${CI_PFY_TOKEN}"

# Commands now authenticate automatically
pfy project list
pfy application list --tenant my-tenant

GitHub Actions

- name: List applications
  run: pfy application list --tenant production
  env:
    PFY_MANAGER_URL: ${{ secrets.PFY_MANAGER_URL }}
    PFY_MANAGER_TOKEN: ${{ secrets.PFY_MANAGER_TOKEN }}

GitLab CI

promote:
  script:
    - pfy application promote --application-id $APP_ID --target-tenant-id $PROD_TENANT_ID --slug $APP_SLUG
  variables:
    PFY_MANAGER_URL: $PFY_MANAGER_URL
    PFY_MANAGER_TOKEN: $PFY_MANAGER_TOKEN

Troubleshooting

Authentication Failed

If commands fail with authentication errors:

1. Verify the token is valid: try pfy project list; check expiry/revocation in the Manager's PAT list
2. Check server URL: verify it is accessible, includes the protocol (https://), no typos
3. Re-login: pfy login --server <url> --token <token>

Connection Refused

If the Manager is unreachable:

# Test connectivity (GraphQL endpoint)
curl https://manager.example.com/query

# Check TLS certificate (if issues)
pfy --insecure-skip-tls-verify login --server https://manager.example.com --token <token>

Permission Denied

If config file can't be written:

# Check directory permissions
ls -la ~/.pfy/

# Create directory if missing
mkdir -p ~/.pfy
chmod 700 ~/.pfy

# Retry login
pfy login --server <url> --token <token>

Security Considerations

Token Storage

• Tokens stored in plaintext in ~/.pfy/config.yaml
• File permissions restrict access to owner only
• Consider using OS keychain for enhanced security (future enhancement)

Network Security

• Always use HTTPS for production
• Avoid --insecure-skip-tls-verify in production
• Verify TLS certificates

Access Control

• Separate tokens for dev/prod
• Regular token rotation
• Audit token usage via the PAT list's "last used"

Planned: Browser Single Sign-On (not yet implemented)

Not yet implemented

Everything in this section is a design for a future release, not current behavior — see Known Issues. Today pfy login only supports --server/--token (both required).

By default, login would use browser single sign-on: it would sign you in through the platform's identity provider and provision a named PAT for the CLI automatically — no copying tokens out of the Manager UI. The flow would be a device-authorization grant, so it would also work over SSH and on headless machines: the CLI would print a URL and a short user code you could open from any browser. Passing the existing --token/--token-stdin flags would skip the browser entirely — the CI path.

How It Would Work

┌──────────────┐  1. start session          ┌──────────────┐
│   pfy login  │───────────────────────────▶│   Manager    │
│              │◀───────────────────────────│              │
│  ephemeral   │  verification URL          └──────┬───────┘
│  keypair     │  + user code                      │
│  (RAM only)  │                                   │ 2. sign in via
│              │                                   │    OIDC and approve
│              │           ┌───────────┐           │    on the consent page
│              │           │  Browser  │◀──────────┘
│              │           └───────────┘  shows: user code,
│              │                          token name, machine, IP
│              │  3. poll                 ┌──────────────┐
│              │─────────────────────────▶│   Manager    │
│              │◀─────────────────────────│              │
│              │  PAT, encrypted to the   └──────────────┘
│              │  CLI's public key (single-read)
│              │
│  4. decrypt in RAM, save PAT to ~/.pfy/config.yaml (0600)
└──────────────┘

1. The CLI would generate an ephemeral keypair in memory (never written to disk) and start a login session at the Manager.
2. The browser would open the verification URL (also printed, with the user code, for SSH sessions). The user would authenticate through the normal OIDC sign-in and land on a consent page showing the user code, the token name, and the requesting machine and IP — approving only if the code matches is what would prevent someone else's login request from being authorized.
3. On approval, the Manager would mint a PAT named pfy/<user>@<host>/<timestamp> and return it sealed to the CLI's public key; the sealed token could be fetched exactly once.
4. The CLI would decrypt it in memory and persist only the PAT to ~/.pfy/config.yaml.

The minted token would be a normal PAT: it would appear in the PAT list in the Manager (name, last used), revocable there at any time.

Planned Flags

Flag	Description
--web	Force the browser flow (would be the default when no token flag is given)
--no-web	Refuse the browser flow; fail unless a token is provided

(--token-stdin is not part of this planned work — it already exists today; see Flags.)

Planned Commands

• pfy whoami — would print the manager URL and token validity (and PAT name, if exposed), so onboarding has a one-command "is my setup working" check; would also let login verify a token before saving it
• pfy logout — would remove the saved token from ~/.pfy/config.yaml

See Also

• Configuration - Configuration details
• Quick Start - Getting started guide
• project - Manage projects