Skip to main content
Every shugo command, with the flags it actually takes. The shugo CLI is a thin wrapper over @shugo-protocol/sdk: each command builds a transaction with the SDK, signs it with the keypair you specify, and submits it. For a guided walkthrough with example output, start with the Quickstart.

​
Installation

Install the CLI package and its Solana dependencies using your package manager:
npm
The package provides the shugo command. If your package manager does not expose it on your shell path, run it through the package manager’s executable runner or check that your package’s binary directory is on PATH.

​
Who signs what

Shugo has two signing roles, and mixing them up is a common mistake. Every command that sends a transaction takes --keypair, and it must be the right party’s key.

​
Global options

Note: --url devnet resolves to Solana’s public Devnet endpoint, which can be heavily rate-limited. For anything beyond a quick check, pass a full RPC URL from a provider such as Helius or QuickNode.
Amounts use the mint’s normal token units, not base units. For example, --per-call-cap 50.5 means 50.5 tokens. The CLI reads the mint’s decimals from the chain and converts the amount for you. It rejects values with more decimal places than the mint supports.

​
create-policy

Creates a policy and registers it as delegatee on a real Subscriptions & Allowances (S&A) delegation in one transaction. If the human does not yet have an S&A authority for the mint, the command initializes one first. Signer: Human (the policy owner).

​
Options

The command prints the policy, delegation, and subscription authority addresses, along with the transaction signature. Keep the policy and delegation addresses; both are required by pull.

​
show

Reads a policy and prints its state. No keypair is needed.
Example output:
pulled this window is the raw stored counter. If the window has expired, the old figure may still be shown until the next pull resets it. The reset happens when a pull is evaluated, not on a timer. See How windows work.

​
pull

Pulls funds through a policy. Signer: Agent (not the human).

​
Options

If a policy check fails, the transaction is rejected during simulation and the program’s logs are shown; the transaction is not submitted. See the error reference.

​
pause and resume

These commands provide the policy kill switch. pause causes future pulls against the policy to fail immediately; resume re-enables them. Signer: Human (the policy owner).

​
update-policy

Changes a policy’s agent, caps, window length, or allowlist. Signer: Human (the policy owner).
Warning: update-policy replaces the entire configuration; it is not a partial patch. Every configuration flag is required, so pass the current value for any setting you do not want to change. Run show first and copy the current values.
This command does not change paused, the amount already pulled in the current window, or the window’s start. Use pause or resume to change the paused state. For the behavior of limits changed mid-window, see Velocity Caps.

​
Troubleshooting

This is usually caused by an unset shell variable. An empty $AGENT expands to no argument, so --agent $AGENT --per-call-cap 50 can become --agent --per-call-cap 50, causing the next flag to be consumed as the missing value.Check the variable with echo "AGENT=[$AGENT]" and export it again if needed. Shell variables also do not automatically carry over to a new terminal tab.
The address may be incorrect, or the CLI may be connected to a different cluster from the one where the policy was created. Check --url.
A Shugo policy check rejected the pull. This is expected when a policy constraint is violated. 0x1770 is Paused; see the error table for the other codes.
S&A error 136, StaleSubscriptionAuthority, means the delegation was created against the wrong generation ID for the human’s S&A authority. Current builds handle this automatically. If you see this error, make sure you are using a recent SDK and CLI build.