@leeguoo/wrangler-accounts 0.1.5 → 1.0.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 (5) hide show
  1. package/README.md +117 -45
  2. package/bin/wrangler-accounts.js +623 -174
  3. package/completions/wrangler-accounts.zsh +33 -8
  4. package/package.json +7 -3
  5. package/skills/wrangler-accounts/SKILL.md +270 -0
package/README.md CHANGED
@@ -1,99 +1,171 @@
1
1
  # wrangler-accounts
2
2
 
3
- Local CLI to manage multiple Cloudflare Wrangler login profiles by saving and swapping the Wrangler config file.
3
+ AWS-style multi-account convenience for Cloudflare Wrangler. Run commands against different Cloudflare accounts in parallel shells without switching global state.
4
+
5
+ ```bash
6
+ wrangler-accounts login work # first-time setup (isolated)
7
+ wrangler-accounts default work # set persistent default
8
+ wrangler-accounts deploy # uses default profile
9
+ wrangler-accounts --profile personal deploy
10
+ wrangler-accounts exec personal -- npm run release
11
+ ```
12
+
13
+ Two shells side by side, two different Cloudflare accounts, zero interference:
14
+
15
+ ```bash
16
+ # terminal 1
17
+ wrangler-accounts --profile work tail my-worker
18
+
19
+ # terminal 2
20
+ wrangler-accounts --profile personal dev
21
+ ```
4
22
 
5
23
  ## What it does
6
24
 
7
- - Save the current Wrangler config as a named profile
8
- - Switch between profiles by copying a saved config into place
9
- - List or inspect status (active profile and matching profile)
10
- - Optional automatic backups when switching
25
+ Every execution runs `wrangler` inside a per-invocation **shadow HOME** — a temporary directory that mirrors most of your real home, except `.wrangler/config/default.toml` is a symlink pointing at the saved profile's config. Token refreshes flow back to the profile automatically. Nothing touches your real `~/.wrangler`. Two parallel invocations get two independent shadow HOMEs.
26
+
27
+ ## Install
11
28
 
12
- ## Install (npm)
29
+ You need **two** things to get the full experience — the CLI binary (what actually runs) and the AI agent skill (what teaches your AI coding agent how to use it). Install both:
13
30
 
14
31
  ```bash
32
+ # 1. The CLI (always required)
15
33
  npm i -g @leeguoo/wrangler-accounts
34
+
35
+ # 2. The AI agent skill (recommended if you use Claude Code / Cursor / Codex / etc.)
36
+ npx skills add leeguooooo/wrangler-accounts -g -y
16
37
  ```
17
38
 
18
- ## Install (local)
39
+ The CLI works standalone — you can skip step 2 if you don't use an AI coding agent. The skill is just markdown documentation the AI reads; it cannot run anything without the CLI installed.
19
40
 
20
- From this repo:
41
+ ### Why two steps?
21
42
 
22
- ```bash
23
- npm link
24
- ```
43
+ | | Installs | For |
44
+ |---|---|---|
45
+ | `npm i -g @leeguoo/wrangler-accounts` | The `wrangler-accounts` executable onto your `PATH` | Your shell |
46
+ | `npx skills add leeguooooo/wrangler-accounts` | `SKILL.md` (markdown) into your AI agent's skills directory | Your AI agent to read |
47
+
48
+ The AI will tell you to run commands like `wrangler-accounts --profile work deploy`; without step 1 those commands fail with "command not found".
25
49
 
26
- Or run directly:
50
+ ### AI agent skill — more options
51
+
52
+ The repo ships an Agent Skill (`skills/wrangler-accounts/SKILL.md`) with multi-account deploy recipes, troubleshooting, CI guidance, and invariants AI can rely on. [skills.sh](https://skills.sh)'s CLI auto-detects which agent you use (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, and 40+ others) and installs to the right directory.
27
53
 
28
54
  ```bash
29
- node bin/wrangler-accounts.js <command>
55
+ npx skills add leeguooooo/wrangler-accounts -g -y # user-global, non-interactive
56
+ npx skills add leeguooooo/wrangler-accounts # project-scoped, interactive
57
+ npx skills add leeguooooo/wrangler-accounts -a claude-code cursor # specific agents only
58
+ npx skills add leeguooooo/wrangler-accounts --list # preview without installing
30
59
  ```
31
60
 
61
+ After both are installed, ask your AI agent something like "deploy my worker to the work account" or "set up a new Cloudflare profile" and the skill will guide it through the right commands.
62
+
32
63
  ## Usage
33
64
 
34
65
  ```bash
66
+ wrangler-accounts <wrangler-args...> # uses default profile
67
+ wrangler-accounts --profile <name> <wrangler-args...>
68
+ wrangler-accounts -p <name> <wrangler-args...>
69
+ WRANGLER_PROFILE=<name> wrangler-accounts <wrangler-args...>
70
+
71
+ wrangler-accounts exec <name> # interactive subshell
72
+ wrangler-accounts exec <name> -- <cmd> [args] # one command
73
+
74
+ wrangler-accounts login <name> # isolated OAuth login
75
+ wrangler-accounts default [name | --unset] # manage persistent default
76
+ wrangler-accounts whoami [--profile <name>] # show resolved identity
35
77
  wrangler-accounts list
36
78
  wrangler-accounts status
37
- wrangler-accounts login work
38
- wrangler-accounts save work
39
- wrangler-accounts use personal
40
- wrangler-accounts remove old
79
+ wrangler-accounts save <name> # snapshot current Wrangler config
80
+ wrangler-accounts sync <name> # refresh a profile from current login
81
+ wrangler-accounts sync-default # refresh the default profile
82
+ wrangler-accounts remove <name>
83
+ wrangler-accounts gc [--older-than 1h] # clean stale shadow HOMEs
41
84
  ```
42
85
 
86
+ ## Profile resolution order
87
+
88
+ When you run `wrangler-accounts <wrangler-args>`, the active profile is resolved in this order:
89
+
90
+ 1. Explicit `--profile <name>` / `-p <name>`
91
+ 2. Positional shorthand: `wrangler-accounts <profile> <wrangler-args...>` (only when `<profile>` matches a saved profile name)
92
+ 3. `$WRANGLER_PROFILE`
93
+ 4. `profilesDir/default` (set via `wrangler-accounts default <name>`)
94
+ 5. Hard error with actionable hint
95
+
96
+ ## When to use `wrangler-accounts` vs. native env vars
97
+
98
+ `wrangler-accounts` is a **local developer convenience** for juggling multiple OAuth sessions on your workstation. It is not the right primitive for CI.
99
+
100
+ - **Local dev, multiple accounts** → `wrangler-accounts`
101
+ - **CI / deploy pipelines** → **`CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` with plain `wrangler`**. Wrangler is designed to read those env vars natively. Create an API token in the Cloudflare dashboard with the scopes your pipeline needs, set the two env vars in your CI secrets, and call `wrangler deploy` directly — no `wrangler-accounts` involved.
102
+ - **Shared scripts** that run locally or in CI → parameterize on `WRANGLER_PROFILE` so devs can run them with `WRANGLER_PROFILE=work wrangler-accounts ./deploy.sh`.
103
+
43
104
  ## Options
44
105
 
45
106
  ```text
46
107
  -c, --config <path> Wrangler config path
47
- -p, --profiles <path> Profiles directory
48
- --json JSON output for all commands
49
- --plain Plain output for list (one name per line)
108
+ --profiles <path> Profiles directory (long form only)
109
+ -p, --profile <name> Profile name for this invocation
110
+ --json JSON output
111
+ --plain Plain output for list (one name per line)
112
+ --include-backups Include backup profiles in list/status
50
113
  -f, --force Overwrite existing profile on save
51
- --backup Backup current config on use (default)
52
- --no-backup Disable backup on use
114
+ --backup Backup current config on use (default)
115
+ --no-backup Disable backup on use
116
+ --unset With 'default': clear the persistent default
117
+ --older-than <dur> With 'gc': age threshold (e.g. 1h, 30m, 7d)
118
+ -h, --help Show help
53
119
  ```
54
120
 
55
121
  ## Environment variables
56
122
 
57
- - WRANGLER_CONFIG_PATH
58
- - WRANGLER_ACCOUNTS_DIR
59
- - XDG_CONFIG_HOME
123
+ - `WRANGLER_PROFILE` — profile to use when no `--profile` flag is given
124
+ - `WRANGLER_CONFIG_PATH` — Wrangler config path override
125
+ - `WRANGLER_ACCOUNTS_DIR` — profiles directory override
126
+ - `XDG_CONFIG_HOME` — fallback base for the profiles directory
60
127
 
61
- ## JSON output
128
+ Inside an isolated session, these are automatically set for the child process:
62
129
 
63
- Use `--json` for machine-readable output.
130
+ - `HOME` — the shadow HOME
131
+ - `WRANGLER_PROFILE` / `WRANGLER_ACCOUNT` — current profile name (useful for shell prompt integration)
132
+ - `WRANGLER_ACCOUNT_REAL_HOME` — path to your real home (escape hatch)
133
+ - `WRANGLER_REGISTRY_PATH`, `WRANGLER_CACHE_DIR`, `WRANGLER_LOG_PATH` — pointed back at real HOME so Miniflare dev registry, workerd cache, and debug logs are shared across profiles
134
+ - `CLOUDFLARED_PATH` — set when `cloudflared` is on your PATH
135
+ - `WRANGLER_SEND_METRICS=false`
64
136
 
65
- Examples:
137
+ ## Breaking changes in 1.0
66
138
 
67
- ```bash
68
- wrangler-accounts list --json
69
- wrangler-accounts status --json
70
- wrangler-accounts use personal --json
71
- ```
139
+ - **`-p` is now `--profile`** (was `--profiles` in 0.1.x). Use the long form `--profiles <path>` to specify the profiles directory.
140
+ - **`use` is deprecated**. It still works but prints a deprecation warning on stderr. Use `default <name>` for persistence or `--profile <name>` for one-shot execution.
141
+ - **`sync-active` is deprecated**, replaced by `sync-default`. The alias still works with a warning.
142
+ - Profile names matching management subcommand names (`exec`, `default`, `whoami`, `gc`, `login`, `list`, `status`, `save`, `sync`, `sync-default`, `remove`, `use`, `sync-active`) cannot be reached via positional shorthand. Use `--profile <name>` instead.
143
+ - First-time setup of a new profile via `wrangler-accounts login <name>` no longer touches your real `~/.wrangler/config/default.toml`. All credential writes go directly into the profile directory.
72
144
 
73
- ## Defaults
145
+ ## Defaults and paths
74
146
 
75
- If you do not specify a config path, the CLI checks for these and uses the first existing path:
147
+ If you do not specify a config path, the CLI checks these paths and uses the first existing one:
76
148
 
77
- - ~/.wrangler/config/default.toml
78
- - ~/Library/Preferences/.wrangler/config/default.toml
79
- - ~/.config/.wrangler/config/default.toml
80
- - ~/.config/wrangler/config/default.toml
149
+ - `~/.wrangler/config/default.toml`
150
+ - `~/Library/Preferences/.wrangler/config/default.toml`
151
+ - `~/.config/.wrangler/config/default.toml`
152
+ - `~/.config/wrangler/config/default.toml`
81
153
 
82
154
  The profiles directory defaults to:
83
155
 
84
- - $XDG_CONFIG_HOME/wrangler-accounts (if set)
85
- - ~/.config/wrangler-accounts
156
+ - `$XDG_CONFIG_HOME/wrangler-accounts` (if set)
157
+ - `~/.config/wrangler-accounts`
86
158
 
87
159
  ## Notes
88
160
 
89
161
  - Profile names accept only letters, numbers, dot, underscore, and dash.
90
- - On `use`, the current config is backed up into `__backup-YYYYMMDD-HHMMSS` unless you pass `--no-backup`.
91
- - `login <name>` overwrites an existing profile with the same name.
162
+ - Saved OAuth sessions can expire. If a profile is expired, running it will stop and tell you to run `wrangler-accounts login <name>` again.
163
+ - Backups from the deprecated `use` command are hidden from `list` and `status` unless you pass `--include-backups`.
92
164
 
93
165
  ## Discoverability (SEO / GEO / AI search)
94
166
 
95
- This project is a Cloudflare Wrangler multi-account switcher for global teams.
96
- Keywords: Cloudflare Workers account manager, Wrangler login profiles, multi-account, account switcher, geo-distributed ops, AI search indexing.
167
+ Cloudflare Wrangler multi-account switcher for global teams.
168
+ Keywords: Cloudflare Workers account manager, Wrangler login profiles, multi-account, account switcher, AWS-style profile, per-invocation isolation, OAuth profile management.
97
169
 
98
170
  ## Shell completion (zsh)
99
171