cloudhop 0.1.1 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +113 -48
  2. package/dist/cli.js +2015 -664
  3. package/package.json +11 -5
package/README.md CHANGED
@@ -1,77 +1,142 @@
1
1
  <p align="center">
2
- <img src="https://raw.githubusercontent.com/dayepesb/cloudhop/main/assets/logo.svg" width="96" height="96" alt="cloudhop logo">
2
+ <img src="https://raw.githubusercontent.com/dayepesb/cloudhop/main/assets/logo.svg" width="88" height="88" alt="cloudhop logo">
3
3
  </p>
4
4
 
5
5
  <h1 align="center">cloudhop</h1>
6
6
 
7
7
  <p align="center">
8
- Hop between cloud accounts, roles and regions with one command.<br>
9
- Automatic login, no access keys.
8
+ <strong>Every cloud account, one short alias away.</strong><br>
9
+ Sign in once per portal, give each account and role a short alias, and let
10
+ cloudhop log you in again only when a session has expired. No access keys.
10
11
  </p>
11
12
 
12
13
  <p align="center">
13
14
 
15
+ [![npm](https://img.shields.io/npm/v/cloudhop?color=1767c2)](https://www.npmjs.com/package/cloudhop)
14
16
  [![Pipeline](https://github.com/dayepesb/cloudhop/actions/workflows/pipeline.yml/badge.svg)](https://github.com/dayepesb/cloudhop/actions/workflows/pipeline.yml)
15
- [![npm](https://img.shields.io/npm/v/cloudhop)](https://www.npmjs.com/package/cloudhop)
16
- [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
17
+ [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-1767c2)](https://github.com/dayepesb/cloudhop/blob/main/LICENSE)
18
+ [![Docs](https://img.shields.io/badge/docs-dayepesb.github.io%2Fcloudhop-ff7a59)](https://dayepesb.github.io/cloudhop/)
17
19
 
18
20
  </p>
19
21
 
20
- > 🚧 Early preview. AWS works today; Azure and Google Cloud are planned.
21
-
22
22
  ```bash
23
- npm i -g cloudhop
24
- cloudhop setup # add an SSO portal or personal account
23
+ npm install --global cloudhop
24
+ cloudhop setup # add your SSO portal, sign in, pick accounts
25
+ hop acme-prod s3 ls # runs `aws s3 ls` as that account, role and region
26
+ ```
27
+
28
+ ## Why cloudhop
29
+
30
+ Working with several AWS SSO portals and personal accounts usually means
31
+ copying access keys, editing `~/.aws/config` by hand and running
32
+ `aws sso login` again and again. cloudhop does that part for you:
33
+
34
+ - **One sign-in per portal.** Add an IAM Identity Center portal once; cloudhop
35
+ finds every account and role you can use and turns the ones you pick into
36
+ aliases.
37
+ - **Logs in only when needed.** Nothing runs in the background. When you use
38
+ an alias with an expired session, cloudhop renews it silently or opens the
39
+ browser, refreshes that portal's accounts, then runs your command.
40
+ - **No access keys, ever.** Only temporary credentials: IAM Identity Center
41
+ for companies, `aws login` for personal accounts.
42
+ - **Works with your tools.** Aliases are real profiles in `~/.aws/config`, so
43
+ Terraform, the AWS SDKs and your IDE see them too. `cloudhop exec` covers
44
+ everything else.
45
+ - **Terminal or browser.** `cloudhop ui` opens a local page to add portals,
46
+ pick accounts and change regions.
47
+
48
+ ## Everyday use
49
+
50
+ | You want to | Run |
51
+ | --- | --- |
52
+ | Run any `aws` command as an alias | `hop acme-prod ec2 describe-instances` |
53
+ | Check who you are | `hop acme-prod` |
54
+ | Use another region once | `hop acme-prod s3 ls --region eu-west-1` |
55
+ | Give any tool temporary credentials | `cloudhop exec acme-prod -- terraform plan` |
56
+ | See your portals and aliases | `cloudhop ls` |
57
+ | Add another portal or personal account | `cloudhop add` |
58
+ | Create more aliases from a portal | `cloudhop alias acme` |
59
+ | Change an alias' region | `cloudhop region acme-prod us-east-2` |
60
+ | Remove an alias or a portal | `cloudhop rm acme-dev` |
61
+ | Check whether an alias needs a sign-in | `cloudhop status acme-prod` |
62
+ | Do all of it from the browser | `cloudhop ui` |
63
+
64
+ `hop <alias>` is the AWS CLI with the account, role and region already chosen:
65
+ pipes, `--output`, `--query` and exit codes work as with `aws`
66
+ ([more](https://dayepesb.github.io/cloudhop/guides/hop-like-aws/)). Every
67
+ setup command also works with flags, for scripts and dotfiles. See the
68
+ [command reference](https://dayepesb.github.io/cloudhop/reference/commands/).
69
+
70
+ ## Teach your AI assistant
71
+
72
+ Tired of explaining cloudhop to Claude Code, Kiro, Copilot, Cursor or Codex in
73
+ every chat? Teach it once:
25
74
 
26
- hop acme-prod s3 ls # `aws s3 ls` with the right account, role and region
27
- hop acme-prod # who am I?
28
- cloudhop exec acme-prod -- terraform plan # any tool, with temporary credentials
29
- cloudhop ui # or manage everything from a local web page
75
+ ```bash
76
+ cloudhop agent install
30
77
  ```
31
78
 
32
- ## Why
79
+ It installs a skill (and, optionally, the `cloudhop mcp` server) so the
80
+ assistant asks you which alias to use, runs commands with `hop`, checks the
81
+ session first and confirms before changing anything. Skills refresh
82
+ themselves when you upgrade cloudhop.
83
+ [More](https://dayepesb.github.io/cloudhop/guides/ai-assistants/).
84
+
85
+ ## The local web UI
86
+
87
+ `cloudhop ui` serves a page on your own computer (and only there) to manage
88
+ portals, aliases and regions.
89
+
90
+ <p align="center">
91
+ <img src="https://raw.githubusercontent.com/dayepesb/cloudhop/main/assets/ui-screenshot.png" alt="cloudhop ui listing two portals with their aliases, regions and session state" width="840">
92
+ </p>
93
+
94
+ ## Requirements
95
+
96
+ - Node.js 20 or newer.
97
+ - AWS CLI v2 to run commands through aliases (`cloudhop setup` offers to
98
+ install it). Personal accounts need AWS CLI 2.32.0 or newer.
99
+ - macOS, Linux or Windows.
100
+
101
+ ## Security
33
102
 
34
- Working with several AWS SSO portals plus personal accounts means copying
35
- access keys, editing `~/.aws/config` by hand and logging in again and again.
36
- cloudhop is a thin proxy over the AWS CLI that:
103
+ - No long-lived secrets: sessions live in the AWS CLI's own token cache, and
104
+ `~/.aws/credentials` is never written.
105
+ - cloudhop only edits its own block in `~/.aws/config` and never overwrites
106
+ profiles you wrote by hand.
107
+ - The web UI listens on `127.0.0.1` only and needs a one-time key per run.
108
+ - Releases are published by GitHub Actions after a maintainer's approval,
109
+ with npm provenance. Verify with `npm audit signatures`.
37
110
 
38
- - Adds SSO portals and personal accounts interactively.
39
- - Discovers every account and role you have access to and creates aliases.
40
- - Logs you in automatically, only when a session has expired, and refreshes
41
- every account of that portal at the same time.
42
- - Never stores long-lived secrets: it uses AWS IAM Identity Center and
43
- `aws login` temporary credentials.
44
- - Writes standard profiles to `~/.aws/config`, so Terraform, SDKs and IDEs
45
- see the same aliases.
111
+ Found a vulnerability? Please
112
+ [report it privately](https://github.com/dayepesb/cloudhop/security/advisories/new).
46
113
 
47
114
  ## Documentation
48
115
 
49
- [dayepesb.github.io/cloudhop](https://dayepesb.github.io/cloudhop/), in English and Spanish.
116
+ **[dayepesb.github.io/cloudhop](https://dayepesb.github.io/cloudhop/)**, in
117
+ English and [Spanish](https://dayepesb.github.io/cloudhop/es/):
118
+ [getting started](https://dayepesb.github.io/cloudhop/getting-started/),
119
+ [company SSO portals](https://dayepesb.github.io/cloudhop/guides/aws-sso/),
120
+ [personal accounts](https://dayepesb.github.io/cloudhop/guides/personal-accounts/),
121
+ [other tools](https://dayepesb.github.io/cloudhop/guides/other-tools/) and
122
+ [troubleshooting](https://dayepesb.github.io/cloudhop/reference/troubleshooting/).
50
123
 
51
- ## Contributing
124
+ ## Roadmap
52
125
 
53
- ```bash
54
- pnpm install
55
- pnpm test # unit tests
56
- pnpm build && pnpm test:e2e # CLI end-to-end tests (sandboxed)
57
- pnpm exec playwright install chromium && pnpm test:web # web UI tests
58
- pnpm audit # dependency vulnerabilities
59
- pnpm typecheck
60
- pnpm lint
61
- pnpm build # bundles packages/cli/dist/cli.js
62
- node packages/cli/dist/cli.js --help
63
- pnpm docs:dev # documentation site
64
- ```
126
+ AWS is fully supported. **Azure** and **Google Cloud** are next, as providers
127
+ in the same package. The work is broken down into
128
+ [issues on the roadmap](https://github.com/dayepesb/cloudhop/issues?q=is%3Aopen+label%3Aroadmap);
129
+ pick one up!
130
+
131
+ ## Contributing
65
132
 
66
- Read [ARCHITECTURE.md](ARCHITECTURE.md) before changing the code; it also
67
- explains the pipeline and how releases are approved. Use
68
- `CLOUDHOP_HOME` and `CLOUDHOP_AWS_DIR` to try things without touching your
69
- real configuration.
133
+ Contributions are welcome. Start with
134
+ [CONTRIBUTING.md](https://github.com/dayepesb/cloudhop/blob/main/CONTRIBUTING.md)
135
+ and [ARCHITECTURE.md](https://github.com/dayepesb/cloudhop/blob/main/ARCHITECTURE.md),
136
+ and follow the
137
+ [Code of Conduct](https://github.com/dayepesb/cloudhop/blob/main/CODE_OF_CONDUCT.md).
70
138
 
71
139
  ## License
72
140
 
73
- [Apache License 2.0](LICENSE). See [NOTICE](NOTICE).
74
-
75
- Contributions are welcome: read [CONTRIBUTING.md](CONTRIBUTING.md) and the
76
- [Code of Conduct](CODE_OF_CONDUCT.md). Report security problems privately as
77
- described in [SECURITY.md](SECURITY.md).
141
+ [Apache License 2.0](https://github.com/dayepesb/cloudhop/blob/main/LICENSE).
142
+ See [NOTICE](https://github.com/dayepesb/cloudhop/blob/main/NOTICE).