Dev Environment Setup

Your local development environment is where you'll build, test, and publish Phygrid apps using the Phygrid CLI.

Once configured, you'll be able to create edge apps, screen apps, and manage other aspects of your Phygrid workflow from your terminal.

🧰 Prerequisites

✅ A Phygrid Tenant

You'll need access to a Phygrid tenant. If you don't yet have one, please refer to the Tenant Setup guide.

✅ Software Requirements

Before installing the Phygrid CLI, make sure your development machine meets these requirements:

Supported Operating Systems

• macOS 15.4+
• Ubuntu 22.04/24.04

Note: Windows support is coming soon. For now, you can use WSL2 with Ubuntu.

Required Software

• Node.js 22+
• Git CLI

For Edge Apps (Optional)

If you plan to build edge apps, you'll also need:

• Docker Desktop

🛠 Step-by-Step: Environment Setup

1. Install the Phygrid CLI

Install the CLI globally using npm:

npm i -g @phygrid/cli

Verify the installation was successful:

phy --version

If you see the CLI version printed without errors, you're ready to proceed.

2. Authenticate

Connect your CLI to your Phygrid tenant:

phy login

This command will:

• Open your default web browser
• Prompt you to authenticate with your Phygrid account
• Ask you to confirm the login from your device

If you're already logged into your Phygrid tenant in your browser, you can confirm the operation without re-entering credentials.

🔐 Headless Authentication

If you're using the CLI in an environment without a GUI browser, use the device code flow:

phy login --use-device-code

Follow the instructions displayed in your terminal to authenticate using a web browser on another device.

✅ Verify Authentication

Once authentication is complete, verify your CLI connection by listing your available tenants:

phy tenant list

If you see your tenant's name displayed without any errors, your authentication is working correctly and you're ready to proceed.

3. Configure Docker (For Edge Apps)

You must enable the containerd image store, a requirement for proper edge apps image handling with Phygrid.

To do this:

1. Open Docker Desktop
2. Go to Settings → General
3. Enable the option "Use containerd for pulling and storing images"
4. Click Apply & Restart

This feature is available in Docker Desktop ≥ 4.29

✅ Checkpoint

After completing these steps, you should have:

• Phygrid CLI installed, authenticated and working
• Docker configured (if building edge apps)

🔄 Next Steps

With your development environment ready, you can now:

• Provision your first device
• Build your first edge app
• Build your first screen app

🛠 Troubleshooting

CLI Installation Issues

Problem: phy command not found after installation
Solution: Make sure your npm global bin directory is in your PATH:

npm config get prefix

Add <prefix>/bin to your PATH if it's not already there.

Authentication Issues

Problem: Browser doesn't open during phy login
Solution: Use the device code flow: phy login --use-device-code

For additional help, contact support at [email protected].