Skip to main content
Troubleshooting · access

Use when

A read comes back smaller than the person expects, a command is refused, or you must tell the person what you can read.

Looking for something else?

A held change that returned pending (problem A change returned pending). An item that a View hides (problem Something outside the View reads as not found). Building a View (card View).

​
Signs

  • A search, a list or a count returns less than the person says is there.
  • A command is refused, and you do not know whether the role, a scope or a View caused it.
  • penumbra whoami names the credential, and you still cannot say what it may read.
  • The person asks “what can you see in this project?”

​
Why it happens

The result of a call depends on three things. The role comes from the project. The scopes come from the key or the connection. A View, when one limits the credential, narrows what it reads and makes it read-only. Each command shows one or two of the three, so you must run more than one.

​
What Penumbra does

By itself:
  • Prints the kind of credential, where the CLI took it from, the project and the expiry in penumbra whoami, and neither the role nor a View.
  • Prints the role and the state of each command family in penumbra status, and no View.
  • Prints the View that limits the credential in penumbra access me, or says that none limits it, and prints no role.
  • Reports a missing scope or a wait in penumbra status --explain "<command>" for a command that carries a scope or an effect. It reports neither for a View command.
  • Answers a read of an item outside the View as it answers one that does not exist.
You must:
  • Run the commands that answer your question, and read each answer for what it leaves out.
  • Tell the person which limit you found, in the person’s words.
Not handled:
  • No MCP tool reports the kind, the role or the View of a connection.
  • penumbra status does not show a View, so a limited credential looks like a viewer with a small project.

​
Do

  1. Run penumbra whoami. It names the kind of credential and where the CLI took it from (card rule credential.1). If it is not the credential that you meant, stop and read the source line (card rule credential.2).
  2. Run penumbra status. Read the role and the state of each command family.
  3. Run penumbra access me. If it prints “You read only the View”, with a name, the View limits what you read. An item outside it reads as missing (card rule view.15). Go on with problem hidden-reads-as-missing.
  4. For one command, run penumbra status --explain "<command>". It reports a missing scope only for a command that carries a scope. It reports a wait for approval for destructive and paid commands only (card rules credential.3 and approval.2).
  5. Tell the person what you found: the role, any View and its version, and the commands that wait for approval.

​
Don’t

  • Don’t say that an item does not exist because your credential cannot find it. Run penumbra access me first.
  • Don’t use the counts of a limited credential as totals.
  • Don’t remove a View limit to look. penumbra access remove widens access.
  • Don’t use a key or a connected agent to manage keys, access or Brains. They need a person’s session (card rule credential.4).

​
Check

  • You can state the kind of credential, its role and its View, or that no View limits it.
  • You told the person what you could not check.
Card credential, with rules credential.1, credential.3 and credential.4. Card view, with rule view.15. Recipe orient. Problems hidden-reads-as-missing and change-waits-for-approval.

​
Keep going

Credential · View · Something outside the View reads as not found · A change returned pending · Find out where you stand in a project