Note: The opinions and views expressed in this article are my own and do not necessarily reflect those of my employer. My thanks to Wendy Lee and Mark Ryan for helping me polish the content.
In the first part of this series, we used Gemini CLI as an interactive partner to learn the fundamentals of Cloud Pub/Sub.
Let’s quickly recap what we accomplished:
- Ran a Pub/Sub “Hello World”: Guided by conversational prompts, we successfully created a topic and a subscription, published a message, and then pulled it to confirm the end-to-end flow.
- Experienced the power of choice: We saw that Gemini CLI never takes action without our approval, allowing us to review, accept, or modify every command.
- Benefited from proactive cleanup: After our test, Gemini immediately suggested and executed the commands to delete the resources we had created, preventing stray resources and unexpected costs.
With the basics covered, we’re now ready to tackle our original, more complex challenge of configuring a dead-letter topic.
Configure the dead letter topic
This is what I typed for Gemini CLI:
I want to understand the concept of dead letter topics and how to configure one. I want a detailed tutorial to configure a dead letter topic. Help me understand all the aspects of the feature.
Gemini CLI explained the concept and presented a plan:
✦ Tutorial: Configuring a Dead-Letter Topic
We will use gcloud to perform the following:
1. Create a main topic for normal message flow.
2. Create a dead-letter topic to receive failed messages.
3. Create a main subscription with a dead-letter policy.
4. Create a dead-letter subscription to view the failed messages.
5. Test the flow by failing to acknowledge a message.
6. Clean up all resources.
Guided by the prompts, we quickly created the new resources:
- A topic for normal message flow called
test-topic. - A dead letter topic to receive failed messages called
dlt-test. - A subscription for test-topic on which the dead-letter policy is applied called
test-sub. - A subscription for the dead letter topic called
dlt-test-sub.
Gemini CLI correctly identified the test subscription and proposed the gcloud command to apply the policy:
gcloud pubsub subscriptions update test-sub \
--dead-letter-topic=dlt-test \
-- max-delivery-attempts=6
So far, so good. The process was smooth, conversational, and much faster than hunting for the right command-line flags. I was feeling pretty smart.
In case you missed it, I just created a dead-letter topic for a subscription. According to the configuration, if the message delivery failed for 6 times, the message would be delivered to the dead letter topic.
The power of interactive debugging
This is where the story gets interesting. It’s one thing to follow a perfect script and it’s another to solve a problem when things go wrong.
I asked Gemini CLI to help me test the setup. Gemini CLI proposed to publish a message, simulate a failing subscriber by pulling the message 6 times without acknowledging it, and then checking the dead-letter topic. Remember, without an ack, Pub/Sub assumes the subscriber failed and redelivers the message to prevent data loss. We had also previously configured the setting Maximum number of delivery attempts as 6.
We executed the plan, but in the final step where I checked the subscription attached to the dead letter topic, it yielded zero messages. The failed message had not gone to the dead letter topic.
I told my partner what happened.
It seems the message was not found in the dead-letter topic. This is unexpected.
Gemini CLI immediately went into debugging mode.
✦ Okay, let's figure this out. The message should have been forwarded.
Let's check a few things.
- Hypothesis 1: Configuration error. Gemini CLI first checked if the subscription was configured correctly by using the command
gcloud pubsub subscriptions describe test-sub.The output showed the configuration was perfect. - Hypothesis 2: Latency. Gemini CLI suggested we wait a moment and try pulling again. Still nothing.
- Hypothesis 3: Permissions. For a subscription to forward messages to a dead-letter topic, the Pub/Sub service account for the project needs permission to both publish to the dead-letter topic and acknowledge messages on the original subscription. This means the service account requires both the
roles/pubsub.publisherandroles/pubsub.subscriberroles. In this case, the subscriber role was already correctly configured.
✦ The service account needs the roles/pubsub.publisher role on
the dlt-test topic. May I proceed with adding this IAM policy binding?
I agreed. It ran the command to grant the permission. We re-ran the test, and… success. The message appeared in the dead-letter subscription, attributes and all. The Pub/Sub service itself needs permission to publish the undelivered message into the dead-letter topic.
This debugging loop of hypothesize, test, verify, explain, and fix, all within a single conversational flow, is incredibly powerful. What could have been an hour-long debugging nightmare was solved in three prompts.
Turn reactive debugging into proactive setup
That debugging loop was powerful, but it got me thinking. What if we could avoid the error in the first place? Instead of just giving one command at a time, you can instruct Gemini CLI to follow a specific workflow for the entire session. And to avoid retyping these instructions every time, we can store them in a GEMINI.md file.
Gemini CLI can load persistent instructions and context from a GEMINI.md file located either in your project directory or in your home directory (~/.gemini/). This is perfect for defining a “meta-prompt” that shapes Gemini’s behavior for all subsequent interactions in the session. For example, the next time I want to configure a Google Cloud feature, I’ll ensure my GEMINI.md file contains instructions like this:
Hello Gemini. For this session, whenever I ask you to help me configure a
Google Cloud feature, please follow this 'Proactive Dependency Check'
workflow:1. First, guide me through the `gcloud` commands to create the core
resources.
2. Before we move on to testing: Please stop and proactively analyze the
configuration.
3. Identify and list **all** potential dependencies, especially IAM roles
(like service account permissions) and any APIs that must be enabled.
4. After listing the dependencies, please propose the specific `gcloud`
commands or console actions needed to grant these permissions or
enable APIs.
5. We will only proceed to testing after these dependencies are confirmed
to be in place.
For more information about how to edit a GEMINI.md file, see Practical Gemini CLI: Bring your own system instruction by Prashanth Subrahmanyam.
From learner to teacher: generating the tutorial
Now that we had successfully configured and debugged the feature, I asked Gemini CLI to create a tutorial based on our entire interaction.
Based on the interaction we just had, can you create a markdown file called `test.tutorial` that teaches end users how to create and use a dead letter topic in Pub/Sub? Include the concepts and tips that we also discussed.
✦ The tutorial is saved to /home/moiborah/test.tutorial.md.
Gemini CLI generated a complete, well-structured tutorial in Markdown. It included the objectives, setup steps, the core procedure (including the permission fix!), and a cleanup section. It turned our interactive session into a reusable learning asset.
The future of learning is a dialogue
My journey from a blank page to a fully functional and documented feature took a fraction of the time it would have with traditional methods.
Tools like Gemini CLI are more than just command-line assistants. They are also interactive learning partners.
- Learning by doing: The conversational interface encourages hands-on exploration, building a deeper understanding of the underlying commands.
- Safe to fail: The ability to quickly diagnose and fix errors, with the AI guiding the debugging process, removes the frustration from the learning curve.
- From conversation to content: The entire interactive history can be transformed into structured documentation, bridging the gap between exploration and explanation.
As Technical Writers and Developers, our ability to learn and adapt quickly is our greatest asset. Interactive, AI-powered tools now enable us to master new technologies by building, testing, and debugging in a continuous, conversational loop.
What’s next?
Source Credit: https://medium.com/google-cloud/gemini-cli-discover-configure-debug-and-document-a-google-cloud-feature-part-2-d320f017c431?source=rss—-e52cf94d98af—4
