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.
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:vieworganization:view
On top of that, add only what you actually use:
server:view,resources:view: list servers and sitessite:manage-deploys:forge deployserver:manage-logs: reading site and server logsserver:manage-services: restarting services like PHP-FPMsite:manage-commands: running commands such asphp artisanon the serverserver:create-keys: needed once forforge sshto add your keysite: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.