You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds a "Stellar CLI for Agents" section at docs/tools/cli/agent-cli/ covering how to use the Stellar CLI and CLI Skills as an agent wallet. It includes a quickstart, the skills overview, seven cookbook guides (send tokens, balances and metadata, delegated spending, message signing, build and submit, x402 payments, USDT0 on mainnet), and four reference pages (architecture, authority model, output and errors, troubleshooting).
The section sits in the Tools sidebar under Stellar CLI, directly below the Stellar CLI Manual, and in the Tools navbar dropdown directly below Stellar CLI. Subsections are collapsed by default.
This description is too broad: direct RPC reads such as network health, ledger latest, and tx fetch do not simulate a transaction; simulation applies to contract/SAC-style reads. Scope the statement so agents do not infer that every read has simulation semantics.
Not all state-modifying commands use the five-stage pipeline
Not every state-modifying command goes through these five stages: a classic tx new payment/tx send path does not simulate or authorize Soroban entries. This overstates the write path and conflicts with the later guidance that a custom Soroban pipeline must call tx simulate explicitly.
The same overstatement appears here: 2>&1 can hide a successful submit, but retrying the exact same signed envelope is not a double spend; only rebuilding a new envelope can repeat the operation. State that distinction so agents do not treat every retry path as equivalent.
Distinguish rebuilding transactions from resending envelopes
confirmed double-spend is too strong and conflates rebuilding with resending. A parse failure followed by rebuilding the command can submit a second transaction, but resending the same signed envelope is sequence-protected and will not execute it twice.
Soroban transactions require resource fees beyond the base fee
The base fee is not the whole requirement here. Soroban-backed commands such as token transfer also need a resource fee, so a zero-XLM account can produce this error even when it could cover the 100-stroop classic base fee; describe the required transaction fees instead of only the base fee.
Restrict simulation claims to Soroban transactions
every tx new command run simulation is incorrect for classic operations such as payment and change-trust; those are built, signed, and submitted without Soroban simulation. Restrict this sentence to Soroban flows, otherwise an agent will look for a simulation result the CLI never produces.
stellar tx fetch result --hash "$TX" --network testnet
```
**Never retry a timed-out write blindly.** On `transaction submission timeout` the RPC accepted the transaction but never reported a final status, so the outcome is unknown. It can still land later. The command exits 1 and `$TX` can be empty, exactly like a real failure. Take the hash from the stderr line `ℹ️ Signing transaction: <HASH>` (text mode only, since JSON mode writes nothing to stderr) and check `stellar tx fetch result --hash <HASH>`. If it is still not found, read both balances and the source account's sequence number before you decide. Only rebuild the payment once you have confirmed the first one did not land.
@oceans404 now that CLI version 28.1.0 has been released, and the build-from-main process is no longer necessary, can we get this PR updated to just use the "regular" install instructions? also, if there are any other v28-related updates/changes, we should include them, too.
@oceans404 now that CLI version 28.1.0 has been released, and the build-from-main process is no longer necessary, can we get this PR updated to just use the "regular" install instructions? also, if there are any other v28-related updates/changes, we should include them, too.
yep! I was waiting for the CLI release to update this PR - doing that now!
The reason will be displayed to describe this comment to others. Learn more.
Looks good to me! I left one nitpick-y markdown link syntax thing, and some notes about the stellar token transfer-from command that's available in the latest CLI. the transfer-from is probably the only thing i'd block on in this review, though.
Resubmitting the same signed envelope cannot double-spend: its sequence number makes a duplicate idempotent. The dangerous retry is rebuilding a new envelope after treating the parse error as a submit failure, so this sentence should distinguish those cases rather than call every retry a confirmed double-spend.
Account for Soroban resource fees in transfer guidance
This diagnosis uses stellar token transfer as the remediation, but that command is a Soroban call and needs a variable resource fee in addition to the 100-stroop inclusion fee. Calling 100 stroops the transaction fee understates the XLM headroom required; 100 is only the classic-payment minimum.
The reason will be displayed to describe this comment to others. Learn more.
Thanks for turning the 28.1.0 updates around so quickly, @oceans404! I re-ran the transfer-from guidance on testnet and it all checks out. The guides and quickstart are really strong, especially the key-exposure warning in Step 3 and the "Choose a pattern" table in Delegate spending.
I pushed one small commit on top of yours: the Node minimum for the x402 guide (@x402/stellar needs 22+) and a typo in the USDT0 caution.
I'd like to ship this for the developer preview and iterate, so here's what I'd fix now vs. later.
Before merge (all on the README, which currently promises a bit more than the reference pages back up):
Structured JSON Outputs: only the stellar token family returns typed JSON, and tx send/tx new have no --output. Scope the bullet to that and point to Output and errors.
Onchain Diagnostic Errors: drop "and auto-correct parameters."
Safety Architecture: the intro says "rather than prompt compliance," but item 3 is prompt compliance. Soften the intro or move item 3.
"Onchain Governance": rename to something like "Spending limits," since governance means protocol decisions on Stellar.
Version note: a line like "Verified against stellar-cli 28.1.0" near the top.
Nits: link "[here]" as the Stellar CLI Manual, and match the "Where to go next" labels to page titles.
Later (follow-ups are fine):
Bring Architecture and Authority model in line with the guides' voice.
Consolidate repeated error details (#13 appears on 8 pages) into Output and errors and Troubleshooting.
File the CLI rough edges the pages document (the #6 message, secure-store stranding, no keys rename, and no simulate-only transfer-from) as stellar-cli issues.
Eventually, consider whether this section should sync from stellar-cli like the cookbook does.
Happy to approve once the "before merge" bits are in. Thanks again!
Safety Architecture: the intro now says the first two items are enforced by the network or a human signer, and the third (smallest-unit amounts) is a convention the agent follows.
"Onchain Governance" is now "Spending Limits".
Version note: added "Verified against stellar-cli 28.1.0." under the intro.
Nits: "[here]" now reads "Stellar CLI Manual", and the "Where to go next" labels match the page titles ("Delegate spending", "Authority & Security Model").
I'll take the "later" items as follow-ups, including filing the CLI rough edges as stellar-cli issues.
This incorrectly says every tx new command simulates before signing. In v28.1.0, tx new only builds the envelope (as this section's build-only guidance also says at build-and-submit-transactions.mdx:27-28,54); only contract invoke performs automatic simulation. Please distinguish the two and tell readers to run stellar tx simulate explicitly for a tx new pipeline.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ElliotFriend
left a comment
Adds a "Stellar CLI for Agents" section at
docs/tools/cli/agent-cli/covering how to use the Stellar CLI and CLI Skills as an agent wallet. It includes a quickstart, the skills overview, seven cookbook guides (send tokens, balances and metadata, delegated spending, message signing, build and submit, x402 payments, USDT0 on mainnet), and four reference pages (architecture, authority model, output and errors, troubleshooting).The section sits in the Tools sidebar under Stellar CLI, directly below the Stellar CLI Manual, and in the Tools navbar dropdown directly below Stellar CLI. Subsections are collapsed by default.