Team Onboarding

How to invite new team members to your project and grant them access to the right environments.

Overview

Adding a new team member involves three steps:

  1. New member sets up envctl — Install and create their identity
  2. You create an invitation — Using their public key
  3. They accept and sync — Join the project and receive secrets

Step 1: New Member Setup

The new team member needs to install envctl and create their identity. Share these instructions with them:

# Install envctl
$ curl -fsSL https://raw.githubusercontent.com/uradical/envctl/main/install.sh | sh

# Create identity
$ envctl init
Enter a passphrase (min 8 characters):
✓ Identity created

# Get public key to share
$ envctl whoami --verbose
Name: bob-laptop
Fingerprint: sha256:8d4e2f1a...
Public key: 8d4e2f1a5b6c7d8e9f0a1b2c3d4e5f6a...

They need to send you their public key (the long hex string). This can be shared over any channel—it's not sensitive.

Verifying identity

For high-security environments, verify the fingerprint through a separate channel (phone call, video chat, in person) to prevent man-in-the-middle attacks.

Step 2: Create the Invitation

Once you have their public key, create an invitation:

$ envctl project invite bob --pubkey 8d4e2f1a5b6c7d8e9f0a1b2c3d4e5f6a...
✓ Invitation created

Share this with bob:

  envctl join eyJwcm9qZWN0IjoibXlhcHAi...

Invite expires in 10 minutes.

Send the envctl join ... command to the new team member. The invite code contains:

  • Project name and configuration
  • Your identity (for verification)
  • Initial environment access
  • Expiration timestamp

Controlling Initial Access

By default, new members get access to the dev environment only. You can customize this:

# Grant dev and staging access
$ envctl project invite bob --pubkey 8d4e... --env dev,staging

# Grant all environments (use with caution)
$ envctl project invite bob --pubkey 8d4e... --env dev,staging,prod

# Grant admin role
$ envctl project invite bob --pubkey 8d4e... --role admin

Roles

Role Can View Secrets Can Modify Secrets Can Manage Members
reader Yes No No
member Yes Yes No
admin Yes Yes Yes

Step 3: Accept the Invitation

The new team member runs the join command in their project directory:

$ cd ~/projects/myapp
$ envctl join eyJwcm9qZWN0IjoibXlhcHAi...

✓ Joined project "myapp"
  Environments: dev, staging
  Invited by: alice (sha256:7f3a9b2c...)

Syncing secrets...

This creates a .envctl/ directory and begins syncing secrets for the environments they have access to.

Start the Daemon

For ongoing sync, they should start the daemon:

$ envctl daemon start
✓ Daemon started
  P2P port: 7834

Step 4: Verify Sync

Both parties should verify that sync is working:

On the New Member's Machine

$ envctl status
Project: myapp
Environment: dev (3 secrets)
✓ Synced with 1 peer

$ envctl env var list
Variables in myapp/dev:

DATABASE_URL = postgres://...
API_KEY      = sk_de...23
DEBUG        = true

On Your Machine

$ envctl project members
Members of myapp:

Name    Role    Environments    Joined
----    ----    ------------    ------
alice   admin   dev,staging,prod   2024-01-05
bob     member  dev,staging        2024-03-01

Granting Additional Access Later

You can grant access to more environments after someone joins:

# Grant prod access
$ envctl project grant bob --env prod
✓ Granted bob access to prod

# Verify
$ envctl project access bob
Access for bob in myapp:

Environment   Role      Since
-----------   ----      -----
dev           member    2024-03-01
staging       member    2024-03-01
prod          member    2024-03-01

You can also revoke access:

$ envctl project revoke bob --env prod
✓ Revoked bob's access to prod

Troubleshooting Onboarding

Invite Expired

Invites expire after 10 minutes by default. Create a new one:

$ envctl project invite bob --pubkey 8d4e... --ttl 30m

Sync Not Working

Check that both parties have the daemon running:

$ envctl daemon status
✓ Daemon running (PID 12345)
  Connected peers: 1

If on different networks, you may need to configure the relay:

$ envctl project relay set relay.envctl.dev

Wrong Environments

If someone needs different access than initially granted:

# Grant missing environment
$ envctl project grant bob --env staging

# Revoke environment they shouldn't have
$ envctl project revoke bob --env prod

Best Practices

Principle of Least Privilege

Start new members with minimal access:

# New developer: dev only
$ envctl project invite newdev --pubkey ... --env dev

# After onboarding: add staging
$ envctl project grant newdev --env staging

# For deploys: add prod
$ envctl project grant newdev --env prod

Use the Relay for Remote Teams

If team members are in different locations or time zones, enable the relay before inviting:

$ envctl project relay set relay.envctl.dev

This ensures secrets sync even when peers aren't online simultaneously.

Verify Identities for Sensitive Projects

Before granting production access, verify the person's fingerprint through a video call or in person:

# They read their fingerprint to you
$ envctl whoami
Fingerprint: sha256:8d4e2f1a...

# You verify it matches what you have
$ envctl project members --verbose
bob: sha256:8d4e2f1a...

Related