smartlead-onboarding
Skill8 starsChanged 6 months agoMITView on GitHub
First-time setup wizard for unofficial-smartlead-cli. Walks the user through getting their public API key (required) and optionally extracting a JWT for advanced features. Friendly, step-by-step, designed for someone who has never used a CLI before. Use this the first time a user invokes any smartlead command and the CLI errors with "API key not configured" — or when the user asks to set up, configure, onboard, get started, install, or first-run.
- Reads credentials
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- audit-mailbox-configSkill
- check-deliverabilitySkill
- clone-campaignSkill
- compare-campaignsSkill
- create-campaignSkill
- launch-campaignSkill
- spam-testSkill
- upload-leadsSkill
- warmup-mailboxesSkill
- weekly-reportSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 7 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 22
If it reports api_key: configured and the user didn't say they want to reconfigure → congrats, they're done.
- Distinctive: line 39
Ask: "Do you already have a Smartlead account?" If no → point them at https://smartlead.ai/signup and stop.
- Distinctive: line 57
Wait for them to paste. Then save it:
- Very specific: line 68
Use the actual key they pasted, obviously — don't write literal <paste-the-key-here>.
- Distinctive: line 87
Don't proceed until this works: If they hit an error, walk them back to Step 3 and re-try with a fresh key.
- Distinctive: line 89
When it works, say something like "Nice, your API key is working ✅ — let's optionally set up the JWT."
- Very specific: line 101
If no → end here. Tell them they can run /smartlead-onboarding again any time to add the JWT later.
- Distinctive: line 102
If yes → continue to Step 6.
- Very specific: line 162
Rotate when in doubt: If a JWT was ever exposed (committed, screenshotted, shared), sign out of Smartlead to invalidate it, then re-run …
- Distinctive: line 181
Should now show all three configured:
- Distinctive: line 209
If the user prefers env vars (e.g., they manage secrets via 1Password / direnv / shell rc files), the CLI reads these too:
- Very specific: line 217
Add to ~/.zshrc or ~/.bashrc to persist.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Before running: verify exact flag names with
smartlead <command> --help. Flag shapes shown below are illustrative — confirm against the actual CLI.
/smartlead-onboarding
You're walking a new user through first-time setup. Assume they've never used a CLI before — be warm, slow, and explain everything. Go one step at a time; don't dump all 10 steps at once.
Step 1 — Are they already set up?
First check current state:
smartlead auth- If it reports
api_key: configuredand the user didn't say they want to reconfigure → congrats, they're done. Tell them to type/in Claude Code to see all the skills available, and suggest/create-campaignas a good first action. - Otherwise → continue to Step 2.
Step 2 — Set expectations
Tell the user (in your own warm voice):
"Setup takes about 5 minutes. There are two pieces:
1. Your public API key (required) — works for most commands. We'll grab this from your Smartlead account settings.
2. A JWT token (optional, recommended) — unlocks advanced features like bulk mailbox config and internal endpoints. We extract it from your browser session. Treat it like a password.
We'll do #1 first, verify it works, then offer #2."
Ask: "Do you already have a Smartlead account?" If no → point them at https://smartlead.ai/signup and stop.
Step 3 — Get the public API key
Walk them through this slowly:
"Okay, let's grab your API key:
- Open https://app.smartlead.ai in your browser and sign in
- Click your profile icon in the top-right corner
- Click Settings
- In the left sidebar, click API Keys
- If you have an existing key, copy it. Otherwise click Generate New API Key and copy the new one.
The key is a long random-looking string. Paste it back here when ready."
Wait for them to paste. Then save it:
cat > ~/.smartleadrc <<EOF
{
"api_key": "<paste-the-key-here>"
}
EOF
chmod 600 ~/.smartleadrcUse the actual key they pasted, obviously — don't write literal <paste-the-key-here>.
Step 4 — Verify the API key works
smartlead campaigns list --output json | head -c 200Interpret the response:
| What you see | What it means | What to do |
Valid JSON ([] or [{...}]) | ✅ Working | Continue to Step 5 |
<!DOCTYPE html> | Cloudflare returned an HTML challenge | Key likely wrong — re-copy from Smartlead |
| "API key not configured" | File didn't save | Check cat ~/.smartleadrc |
| HTTP 401 / "Unauthorized" | Key invalid or revoked | Generate a new one in Smartlead Settings |
Don't proceed until this works. If they hit an error, walk them back to Step 3 and re-try with a fresh key.
When it works, say something like "Nice, your API key is working ✅ — let's optionally set up the JWT."
Step 5 — Offer the JWT setup
Ask the user:
"You're set up for the basics! 🎉 You can stop here if you just need standard commands.
But if you want access to advanced features — bulk mailbox configuration, GraphQL queries, internal endpoints — we can also set up a JWT token. Takes 2 minutes. Want to do it now?"
- If no → end here. Tell them they can run
/smartlead-onboardingagain any time to add the JWT later. Skip to "Wrap up" section. - If yes → continue to Step 6.
Step 6 — Find the session token (no code, just clicks)
Walk the user through this slowly. No Console, no JavaScript — just a few clicks and one copy-paste.
"We need to grab your Smartlead session token. Don't worry, no scary code — just clicks:
- Make sure you're signed in to https://app.smartlead.ai
- Open DevTools: right-click anywhere on the page → Inspect (Or Mac:
Cmd + Option + I, Windows/Linux:F12)- At the top of the DevTools panel, click the Application tab (Not Console, not Network — Application.)
- In the left sidebar, scroll down to Storage → expand Local storage → click https://app.smartlead.ai
- In the table on the right, find the row where the Key is exactly
smartlead- Right-click that row → Copy value (Or click into the cell, press
Cmd+Ato select all, thenCmd+C)- Paste it back here. It'll be a long string of letters and numbers — that's expected, don't worry."
If they hit a problem
| Symptom | Cause | Fix |
No smartlead key in the list | Not signed in, or session expired | Sign in to Smartlead, refresh the page, try again |
| "Storage" not visible in left sidebar | Sidebar section collapsed | Scroll down, click the ▶ to expand sections |
| Value looks short / cut off | Copied the display preview instead of the full value | Right-click the row → Copy value (this copies the full thing) |
Step 7 — Decode and save
Take the raw value the user pasted, decode the base64 envelope, extract both the JWT and sl_api_key, and write them into ~/.smartleadrc alongside the existing public api_key. Walk the user through what you're doing if they ask — explain whatever they want to know.
SL_RAW='<paste-the-value-they-gave-you-here>'
# Decode the base64-encoded session blob and pull out the two tokens
JWT=$(node -e "console.log(JSON.parse(Buffer.from(process.argv[1], 'base64').toString()).auth.token)" "$SL_RAW")
SL_API_KEY=$(node -e "console.log(JSON.parse(Buffer.from(process.argv[1], 'base64').toString()).applicant.user.api_key)" "$SL_RAW")
PUBLIC_KEY=$(jq -r '.api_key' ~/.smartleadrc)
# Write merged config
cat > ~/.smartleadrc <<EOF
{
"api_key": "$PUBLIC_KEY",
"jwt": "$JWT",
"sl_api_key": "$SL_API_KEY"
}
EOF
chmod 600 ~/.smartleadrc
echo "✓ Saved JWT and sl_api_key to ~/.smartleadrc"Security best practices to follow (and explain to the user if they ask)
- Never hardcode tokens in source code, scripts, or commit history. Tokens belong in
~/.smartleadrc(chmod 600), in.envfiles (gitignored), or in env vars exported by the shell — never in a file that gets committed to git. - JWTs are like passwords. Anyone with the JWT can act as the user on Smartlead's internal API surface. Don't paste them in Slack, screenshots, public docs, or PR descriptions.
- Rotate when in doubt. If a JWT was ever exposed (committed, screenshotted, shared), sign out of Smartlead to invalidate it, then re-run
/smartlead-onboardingto get a fresh one. - The decode in this step happens locally on the user's machine. The values land in
~/.smartleadrc(chmod 600, only they can read it). That's the intended end state.
If decode fails
| Error | Cause | Fix |
SyntaxError: Unexpected token | Value got truncated or has whitespace | Re-paste using right-click → Copy value (not select-and-copy) |
Cannot read properties of undefined | Smartlead app changed the schema | Surface to user — schema may have shifted since this skill was written |
Unexpected end of JSON input | Empty input — user pasted nothing | Re-prompt for the value |
Step 8 — Final verification
smartlead authShould now show all three configured:
- ✅
api_key: configured - ✅
jwt: configured - ✅
sl_api_key: configured
Wrap up
Congratulate them. Then give them the important context:
"You're fully set up! 🚀 Three things to know:
- JWTs expire — usually after a few weeks. If commands start returning 401 errors, re-run
/smartlead-onboardingand grab a fresh one. Your public API key doesn't expire.- Keep
~/.smartleadrcprivate. It's chmod 600 (only you can read it). Never commit it to git. Never paste it in a public chat.- What to try next:
/create-campaign— set up a new campaign end-to-end/warmup-mailboxes— apply a verified warmup config to your mailboxes/check-deliverability— audit bounce/reply health on a campaignType
/anytime in Claude Code to see all available skills."
Alternative: env vars instead of config file
If the user prefers env vars (e.g., they manage secrets via 1Password / direnv / shell rc files), the CLI reads these too:
export SMARTLEAD_API_KEY="..."
export SMARTLEAD_JWT_TOKEN="..."
export SMARTLEAD_SL_API_KEY="..."Add to ~/.zshrc or ~/.bashrc to persist.
The CLI checks env vars first, then falls back to ~/.smartleadrc. Either path is fine — pick what fits your workflow.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

