As I started working more deeply with AWS, I noticed a small but recurring workflow:
When debugging an EC2-based application, I often need to quickly answer a few basic questions:
- Is the instance running?
- What type of instance is it?
- Which region and Availability Zone is it in?
- What are its public and private IPs?
- Are the EC2 status checks healthy?
The AWS Console provides all of this information, but sometimes I just want a quick answer from my terminal.
So I built aws-ec2-check, a small open-source CLI for inspecting AWS EC2 instances directly from the command line.
The project is now publicly available on GitHub:
GitHub: https://github.com/devSahinur/aws-ec2-check
The repository is written in TypeScript and is published under the MIT License.
The problem
When working with EC2-based applications, a lot of troubleshooting starts with basic infrastructure information.
For example:
Is the instance running?
Is the instance healthy?
Which Availability Zone is it using?
What's the public IP?
What's the instance type?
Are the EC2 status checks passing?
I could open the AWS Console and look these up.
But when I'm already working in the terminal, switching between tools feels unnecessary for such a small task.
That was the motivation behind the project.
What aws-ec2-check does
The idea is simple:
Terminal
↓
aws-ec2-check
↓
AWS SDK for JavaScript
↓
Amazon EC2
For a specific instance, the CLI is designed to provide useful EC2 information such as instance state, metadata, and health/status information.
A typical command looks like:
aws-ec2-check i-0123456789abcdef0
The project also supports a CLI-first workflow rather than requiring users to interact with the AWS Console.
Why build another AWS tool?
There is already an official AWS CLI.
So I'm not trying to replace it.
The goal of this project is much smaller:
Make one common EC2 inspection workflow convenient from the terminal.
That distinction is important.
I don't think every open-source project needs to become a massive platform.
Sometimes a small developer utility is enough to solve a real annoyance.
How it's built
I chose TypeScript because it fits naturally with my Node.js backend background while giving the project strong typing and a better development experience.
The repository is currently categorized around:
AWS
CLI
DevOps
EC2
Node.js
TypeScript
and is publicly available as devSahinur/aws-ec2-check.
At a high level, the architecture is:
Developer
↓
CLI
↓
TypeScript
↓
AWS SDK for JavaScript
↓
EC2 API
The CLI acts as a small abstraction over the EC2 APIs needed for inspection.
AWS SDK instead of the Console
One thing I wanted to learn from this project was what happens underneath the AWS Console.
When I use the Console, a lot of AWS operations feel like buttons and tables.
When building a CLI with the AWS SDK, those same workflows become explicit API calls.
That makes the architecture easier to reason about:
CLI command
↓
Application logic
↓
AWS SDK
↓
EC2 API
↓
Response
↓
Formatted terminal output
For me, this was a useful way to connect AWS infrastructure knowledge with backend development.
Security matters
Because this tool interacts with AWS, credential handling was one of the parts I paid close attention to.
I don't want AWS credentials embedded in the source code.
The tool should work with AWS's standard credential resolution mechanisms rather than inventing its own authentication approach.
That means developers can use their existing AWS configuration or appropriate AWS roles.
Just as importantly, the tool is intended for inspection, not unnecessary infrastructure modification.
That led to another important design principle:
A small tool should ask for small permissions.
There's no reason for an EC2 inspection tool to require administrator access.
IAM and least privilege
AWS permissions can become dangerous when developers solve every AccessDenied problem by attaching broad policies.
For this project, I wanted the permissions model to follow the same principle I discussed in my earlier IAM article:
Required action
↓
Required resource
↓
Minimum permission
Rather than:
Required action
↓
AdministratorAccess
This is a small CLI, but the security principle is the same as it is for a large production system.
Keeping the CLI simple
I wanted the command structure to stay easy to understand.
The core idea is:
aws-ec2-check <instance-id>
And as the project evolves, additional commands and options can support common workflows without making the CLI feel complicated.
For example:
aws-ec2-check --help
and:
aws-ec2-check --version
make the tool easier to discover and use.
Why TypeScript?
For a small project like this, TypeScript isn't required.
But I still prefer it because it gives me:
- Better type safety
- Better editor support
- Easier refactoring
- Clearer function contracts
- Better maintainability as the project grows
It also keeps the project close to the technologies I already use in backend development.
Testing the project
Another thing I wanted to avoid was creating a CLI that only works on my machine.
A useful open-source project needs to be reproducible.
So the project is structured around the usual development workflow:
npm install
npm run build
npm test
npm run lint
npm run typecheck
The goal is to keep the project easy to validate locally and suitable for automated checks through GitHub.
What I learned building it
The interesting part of building this project wasn't only calling the EC2 API.
It made me think more carefully about the difference between:
"I can write the code."
and:
"I can publish something other developers can actually use."
That difference includes a lot of small details.
CLI design
A CLI needs clear commands and understandable output.
The user shouldn't have to understand the internal implementation just to get an EC2 status.
AWS authentication
AWS credential handling shouldn't be reinvented.
Using established AWS mechanisms is safer and easier to maintain.
Error handling
AWS errors can contain useful technical information, but exposing raw errors to users isn't always the best experience.
A good CLI should turn those failures into useful messages.
Documentation
Open source isn't just about code.
A developer should be able to discover:
What does this tool do?
How do I install it?
How do I authenticate?
What permissions are required?
What commands are available?
What should I do when something fails?
If the README can't answer those questions, the project isn't finished.
What I'd like to add next
The first version is intentionally focused.
But there are several areas that can make the tool more useful over time:
Instance filtering
Tag-based filtering
Multi-region support
JSON output improvements
More detailed health information
Additional EC2 inspection commands
Better automation support
The important part is adding features based on real developer needs rather than adding functionality just to make the project bigger.
Why open source?
One of my goals with this project was to move beyond simply learning AWS privately.
I wanted to follow a cycle like:
Learn
↓
Build
↓
Document
↓
Publish
↓
Get feedback
↓
Improve
That's one of the reasons I'm interested in building in public.
A project becomes more valuable when other developers can inspect it, use it, report issues, and contribute ideas.
Try it
The repository is available here:
https://github.com/devSahinur/aws-ec2-check
It's a public GitHub repository built with TypeScript and focused on AWS EC2 inspection.
You can explore the implementation, open an issue, suggest an improvement, or contribute to the project.
Final takeaway
I didn't want to build a huge AWS platform.
I wanted to solve one small problem:
Make EC2 inspection easier from the terminal.
That small problem turned into a useful learning project covering:
TypeScript + Node.js + AWS SDK + EC2 + IAM + CLI development + Open Source
For me, that's the real value of building small developer tools.
You don't always need a huge project to learn something meaningful.
Sometimes you just need to take one annoying workflow and make it a little better.
Build something small. Make it useful. Publish it. Then keep improving it.
Top comments (0)