Working with clients who have their own Forge account? Stop pasting API tokens

Your sites live in your Forge account, your client's in theirs. The Forge CLI only remembers one token, and org:switch only helps inside one account. A ten-line shell function gives you profiles per account, and one line in your CLAUDE.md makes sure your AI agent deploys with the right one.

Zacharias Creutznacher Zacharias Creutznacher

Working with clients who have their own Forge account? Stop pasting API tokens

If you run your own projects on Laravel Forge and also work on a client project that lives in the client's Forge account, you will hit this sooner or later: you log the Forge CLI into the client account, and suddenly forge deploy for your own site answers with

 1The resource you are looking for could not be found.

Nothing is broken. The Forge CLI simply stores exactly one API token, in ~/.laravel-forge/config.json, together with the currently selected organization and server. Log in with another token and the old one is gone.

#Organizations help, but only within one account

Since Forge 2, the CLI knows organizations. If one Forge user has access to several organizations, you can switch with:

 1forge org:switch
 2forge server:switch

That is the clean solution when you can be invited into the other organization. The catch: inviting members into an organization requires Forge's Business plan on the inviting side. If the client is on a smaller plan, you end up with two separate Forge accounts and two separate tokens, and org:switch cannot bridge them.

#A tiny profile switcher

Since the whole CLI state is a single JSON file, the simplest fix is to keep one copy per account and swap it in. Add this to your ~/.zshrc (it works in bash too):

 1forge-use() {
 2    local dir="$HOME/.laravel-forge/profiles"
 3    mkdir -p "$dir" && chmod 700 "$dir"
 4
 5    if [[ "$1" == "--save" && -n "$2" ]]; then
 6        install -m 600 "$HOME/.laravel-forge/config.json" "$dir/$2.json" && echo "Saved Forge profile: $2"
 7    elif [[ -n "$1" && -f "$dir/$1.json" ]]; then
 8        install -m 600 "$dir/$1.json" "$HOME/.laravel-forge/config.json" && echo "Forge profile: $1"
 9    else
10        echo "Usage: forge-use <profile> | forge-use --save <profile>"
11        echo "Profiles: $(ls "$dir" 2>/dev/null | sed 's/\.json$//' | tr '\n' ' ')"
12    fi
13}

The function is also available as a Gist.

Set up each account once:

 1forge login               # paste the token of this account
 2forge org:switch          # pick the organization
 3forge server:switch       # pick the default server
 4forge-use --save acme     # store it as profile "acme"

From then on, switching is one command:

 1forge-use acme
 2forge deploy acme.com

Calling forge-use without arguments lists your profiles. We name profiles after the Forge organization, not after a single site, because one organization usually hosts several sites. The profile files contain your API tokens, so they are created with 600 permissions in a 700 directory.

#Which token scopes the CLI needs

When you create the API tokens, do not just tick everything. forge login only needs two scopes, without them it fails with a plain "Forbidden.":

  • user:view
  • organization:view

On top of that, add only what you actually use:

  • server:view, resources:view: list servers and sites
  • site:manage-deploys: forge deploy
  • server:manage-logs: reading site and server logs
  • server:manage-services: restarting services like PHP-FPM
  • site:manage-commands: running commands such as php artisan on the server
  • server:create-keys: needed once for forge ssh to add your key
  • site:manage-environment: forge env:pull / env:push. Optional, this lets the token read every secret in your .env

Leave out anything that deletes, transfers or touches billing. A token that leaks should not be able to remove a server.

#Telling your AI agent about it

We let Claude Code run deployments when we explicitly ask for it. An agent does not know which Forge profile is active, and a "not found" from the CLI tends to send it on a long detour. So it gets one short rule.

Since forge-use lives in your own shell, the rule belongs in your personal ~/.claude/CLAUDE.md, not in the project's committed Laravel Boost guidelines, where it would only confuse teammates who do not have the function. One line with a project to profile mapping covers all your projects:

 1- The Forge CLI stores only one API token, so it may be logged into another
 2  account. Before any `forge` command run `zsh -ic 'forge-use <org>'`.
 3  "not found" or "Forbidden" means the wrong profile is active.
 4  Profiles: my-app, my-blog → `mine`; client-app → `client`.
 5  Never deploy on your own initiative.

Note the zsh -ic part: agents usually run commands in a non-interactive shell that does not load ~/.zshrc, so the function would not exist there.

One small extra: if you installed the Forge CLI through Laravel Herd, it lives in ~/Library/Application Support/Herd/bin/forge and is updated together with Herd, so composer global update will not find it.

#This should be built in

A shell function is a workaround. The cleaner place for this is the CLI itself, so we opened a pull request that stores one token per organization: laravel/forge-cli#179. forge login then remembers every account you log into, and forge org:switch picks the right token on its own. If you would like to see it merged, a thumbs up on the PR helps.

Until then: ten lines of shell, no more pasting tokens, and no more deploys that fail because the CLI was still logged into the other account.