Your key
A personal pmo key signs AI sessions and scripts in to PMO; this page covers getting one, where it lives, and what to do when it stops working.
A key is a long secret code, starting pmo_, that tells the PMO server who you are on every command. Most people no longer need one: signing in with your Cross account is the first way in for a person. A key is for AI sessions, scripts and scheduled jobs, or for anyone who prefers one.
Treat the key like a password
Anyone holding your key acts as you. Never paste it into Slack, an email thread, a ticket, a shared document, a commit or a PMO record. If it might have been seen by anyone else, ask the PMO owner to switch it off. That costs you only a new key.
What a key decides
The server works out whose key it is, then does only what that person may do and records every change under their name.
| Who you are | What you see | What you may change | |
|---|---|---|---|
| Comes from | The person the key was issued for | The engagements you have been given | Your role, limited by what each engagement grants you |
| Shows up as | Your name on every change, in every record's history | Records outside your access read as "not found" | A refusal that names the rule and who can do it instead |
Commands accept an "acting as" name. With a key, naming yourself is fine, leaving it out is fine, and naming anybody else is refused.
One key per person or AI session, per computer. Each key is labelled with the computer or session it is for, so a lost laptop's key can be switched off without touching any other. An AI session should have a key of its own, issued for it and for the person who runs it, so every change it makes records both.
Shown once. The server stores only a one-way fingerprint of your key, never the key, so nobody (the owner included) can look it up later. A lost key is replaced, not recovered. Keys do not expire; they stay valid until switched off.
The board is separate. Signing in to the PMO board in a browser uses your email and a password. A key is only for pmo and other programs.
Get a key and put it in
Ask the PMO owner
Tell them which computer or AI session it is for, for example "work laptop". Your work email must be on PMO's team list first; if you have used the board, it already is. pmo cannot issue a key from your computer.
Receive it privately
It arrives as one long line starting pmo_. Copy all of it. It will not be shown again.
Put it in your settings file
If you are installing now, paste it when the install asks. If pmo is already installed, open your settings file and paste the key straight after PMO_KEY=, with no space. Save the file.
notepad "$env:APPDATA\pmo\config"Check it
In a new terminal window, run pmo whoami. It should print your PMO id and your name, for example person:you (Your Name).
Delete the message it came in
Once it works, remove the key from wherever it reached you. The copy in your settings file is the only one you need.
Where the settings file lives
| Computer | Settings file |
|---|---|
| Windows | %APPDATA%\pmo\config |
| Mac and Linux | ~/.config/pmo/config (or under XDG_CONFIG_HOME when that is set) |
PMO_CONFIG names a different file. Only two lines are read, the server address and the key; any other line is ignored:
PMO_API_URL=https://pmo.crossbot.io
PMO_KEY=pmo_…your key…- A key wins. When the
PMO_KEYline holds a key,pmosends the key and ignores any Cross account sign-in on this computer. An empty line means no key. - The window wins over the file. A
PMO_KEYset in the terminal window itself overrides the file. Set but empty in the window, it hides the file's key, so the sign-in is used. - A key's shape is checked first. A key is
pmo_, sixteen characters, an underscore, then the secret. One that is not shaped like that stops the command before anything is sent; it does not fall back to your sign-in. - Mistyped names are ignored. Nothing checks the file when you save it. A misspelled setting name is treated as missing.
- Reinstalling keeps the old key. The install does not rewrite an existing settings file, so a new key goes in by editing it.
- Protection. On a Mac or Linux the install makes the file readable by you alone. On Windows it relies on your user folder's normal protection, so an administrator of the computer can read the key.
When the key stops working
A problem with a key is never fixed by trying harder: either the copy is wrong, or you need a new key.
| What you see | Why | What to do |
|---|---|---|
| PMO_KEY does not hold a key … a half-copied one is the usual cause | The line in your settings file is not the whole key, or has something extra around it. | Paste it again in full. Nothing was sent. |
| … PMO_KEY is not set | The key line is empty, or the settings file is not where pmo looks, and this computer is not signed in with a Cross account either. | Put the key in, or sign in instead. |
| no identity: the key presented is not a live key on this machine | The server does not recognise it: it was switched off, or never issued there. | Ask the PMO owner for a new one. |
| you are …, and --as … names somebody else | A command named someone else as the one acting. | Leave the name out, or use your own. |
| pmo names somebody other than you | A key on the PMO_KEY line belongs to someone or something else. | Empty the line to use your own sign-in, or put in your own key. |
| You lost the computer, or posted the key somewhere | Tell the PMO owner at once. They switch off that key; your other keys keep working. |
A refused key never falls back to nobody
A key that is present and does not check out is refused outright. pmo never quietly carries on as an anonymous user, so a switched-off key cannot keep working without anyone noticing.