Awesome Open Source
Awesome Open Source


Workflow Status Go Report Card GolangCI Codecov MIT License

List view of AWS EC2 instances.

Example as follows.

$ lsec2 -H
INSTANCE_ID            PRIVATE_IP         PUBLIC_IP         TYPE        STATE      TAGS
i-0xxxxxxxxxxxxxx1    t2.micro    running    TagA=ValueA,TagB=ValueB
i-0xxxxxxxxxxxxxx2    t2.medium   running    TagAA=ValueAA
i-0xxxxxxxxxxxxxx3     172.333.333.333    54.333.333.333    t1.large    stopped


Using Homebrew for OS X

$ brew install goldeneggg/tap/lsec2


If you have already installed an old version's lsec2 using brew tap goldenegg/lsec2 command and brew install lsec2 command, please uninstall old version.

# uninstall old tap version
$ brew uninstall lsec2
$ brew untap goldeneggg/lsec2

# and install new tap version
$ brew install goldeneggg/tap/lsec2

Or go get

$ go get -u

Or direct download

Download from latest release


Create ~/.aws/credentials file

If you have already installed aws-cli, I recommend setting up by aws configure command.

Write your credential information in ~/.aws/credentials file.

  • Write a section
    • Default is [default]. It's known as "Profile".
  • Write aws_access_key_id in your section
  • Write aws_secret_access_key in your section
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

More information: session - Amazon Web Services - Go SDK

Or Set environment variables

2 variables are required


Change runtime profile

Use --profile option

aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

aws_access_key_id = YOUR_ACCESS_KEY_ID2
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY2
$ lsec2  # use "default" profile
$ lsec2 --profile test  # use "test" profile

Use profile with AssumeRole



# print all instances info by list view
$ lsec2

Result contains informations of instances as follows

  • instance id
  • private ip address
  • public ip address
  • instance type
  • instance state
  • tags

Show more detail information by typing lsec2 -h

Assign region

You can use 3 patterns

  • assign by --region option (top priority)
$ lsec2 --region ap-northeast-1
  • write region key in ~/.aws/config file
$ vi ~/.aws/config
region = ap-northeast-1
  • set AWS_REGION environment
$ export AWS_REGION=ap-northeast-1

Show more information from public AWS documents

Filter by tag

# filterd by a tag key-value separated by "="
$ lsec2 TagName1=tagvalue1

# filterd by some tags
$ lsec2 TagName1=tagvalue1 TagNameN=tagvalueN

# filterd by a tag multiple values separated by comma
$ lsec2 TagName1=tagvalue11,tagvalue12,tagvalue1N


# with header
$ lsec2 -H

# filter state
$ lsec2 -s running
$ lsec2 -s stopped
$ lsec2 -s OTHER_STATE

# print only private IP address
$ lsec2 -p

# print state with color
# ("running" is green, "stopped" is red, and others are yellow)
$ lsec2 -c

# change column delimiter (default delimiter is TAB)
$ lsec2 -d ,


With peco

peco is a very useful interactive filtering tool.

  • Example: print instances => select instance => SSH to selected instance
# add function to your .bashrc or .bash_profile or other shell dotfile

lssh () {
  IP=$(lsec2 [email protected] | peco | awk -F "\t" '{print $2}')
  if [ $? -eq 0 -a "${IP}" != "" ]
      ssh ${IP}

# load dotfile

# shortcut "lsec2 OPTIONS TAG_FILTERS" => "ssh PRIVATE_IP"
$ lssh TagName1=tagvalue1

With gat

gat is a file posting tool to various services like cat command.

  • Example: print instances => share your slack
# shortcut "lsec2 OPTIONS TAG_FILTERS" => copy this results to your slack channel
$ lsec2 TagName1=tagvalue1 | gat slack


Please follow Contributor's Guide


Bugs: issues


CHANGELOG file for details.


LICENSE file for details.

Special Thanks


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
go (15,152
aws-ec2 (36