Spotify Integration Setup

Connect your Spotify account to automatically add your currently playing song to commit messages. This guide will walk you through the complete setup process.

Prerequisites

• A Spotify account (free or premium)
• Node.js installed (commit-vibes requires Node.js 16+)
• Basic familiarity with terminal/command line

Step 1: Create a Spotify App

First, you need to create a Spotify application in the Spotify Developer Dashboard to get API credentials.

1. Go to Spotify Developer Dashboard
2. Log in with your Spotify account
3. Click "Create app" or "Create an app"
4. Fill in the app details:
   • App name: Choose any name (e.g., "commit-vibes")
   • App description: Optional description
   • Redirect URI: http://127.0.0.1:3000 (important: use IP address, not localhost)
   • Website: Optional, can leave blank or use your GitHub repo URL
5. Check the "I understand and agree to Spotify's Developer Terms of Service" checkbox
6. Click "Save"

Step 2: Get Your Credentials

After creating your app, you'll need to get your Client ID and Client Secret.

1. In your app's dashboard, you'll see your Client ID displayed
2. Click "Show client secret" to reveal your Client Secret
3. Copy both values - you'll need them in the next step

Step 3: Configure commit-vibes

Now you'll add your Spotify credentials to commit-vibes. You can use either environment variables (recommended) or a config file.

Option A: Environment Variables (Recommended)

This is the recommended approach as it keeps credentials out of your codebase.

1. In your project root (or home directory for global config), create a .env file:

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://127.0.0.1:3000

2. Replace your_client_id_here and your_client_secret_here with your actual credentials from Step 2
3. Make sure .env is in your .gitignore file (it should be by default)

Option B: Config File

Alternatively, you can create a config file in the commit-vibes source directory.

1. Navigate to the commit-vibes installation directory (usually in node_modules/commit-vibes/src/config/)
2. Copy the template file:

   cp spotify.template.js spotify.js

3. Edit spotify.js and replace the placeholder values:

   export const SPOTIFY_CONFIG = {
     clientId: "your_actual_client_id",
     clientSecret: "your_actual_client_secret",
     redirectUri: "http://127.0.0.1:3000",
     scopes: ["user-read-currently-playing", "user-read-recently-played"],
   };

Step 4: Set App to Development Mode

For local development, your Spotify app needs to be in Development Mode.

1. In the Spotify Developer Dashboard, go to your app's Settings
2. Find the "App status" or "Application type" section
3. Make sure it's set to "Development Mode" (not Production)
4. If in Development Mode, go to "Users and Access" and add your Spotify account email to the allowed users list
5. Click "Save"

Step 5: Connect Your Account

Now you're ready to connect your Spotify account to commit-vibes.

1. Run the connect command:

   commit-vibes --spotify

2. Your default browser (or Chrome if configured) will open to Spotify's authorization page
3. Log in to Spotify if prompted
4. Review the permissions commit-vibes is requesting:
   • Read your currently playing content - To show what song you're listening to
   • Read your recently played tracks - To show recent songs if nothing is currently playing
5. Click "Agree" or "Authorize"
6. You'll see a success page - you can close the browser tab
7. Return to your terminal - you should see a success message

Step 6: Verify Connection

Test that everything is working correctly.

1. Check your connection status:

   commit-vibes --status

2. You should see:
   • ✨ Spotify is connected!
   • Your currently playing track (if music is playing)
   • Or your most recent track (if nothing is playing)

Troubleshooting

Error: "INVALID_CLIENT: Insecure redirect URI"

This means your redirect URI doesn't match between your code and Spotify dashboard.

• Make sure you're using http://127.0.0.1:3000 (not localhost)
• Verify it's exactly the same in both your .env file and Spotify dashboard
• Check for any trailing spaces or characters
• Make sure your app is in Development Mode

Error: "Spotify token has expired"

Your access token has expired. Simply reconnect:

commit-vibes --spotify

Error: "Spotify is not configured"

commit-vibes can't find your credentials. Check:

• Your .env file exists and is in the correct location
• The environment variables are named correctly: SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET
• There are no typos in the variable names
• If using a config file, make sure it's in the correct location

Browser Opens Safari Instead of Chrome

By default, commit-vibes tries to open Chrome. If it's not available, it falls back to your default browser. To ensure Chrome opens:

• Make sure Chrome is installed
• The code will automatically try Chrome first, then fall back to default

Connection Works But No Music Shows

If your connection is successful but no music appears:

• Make sure Spotify is actually playing music (not paused)
• Try the --status command to see what commit-vibes detects
• Check that your Spotify app has the correct scopes enabled

Disconnecting Spotify

To disconnect your Spotify account:

commit-vibes --disconnect

This will remove your stored tokens. You can reconnect anytime using --spotify.

Security Best Practices

• Never commit your .env file or spotify.js config file to version control
• Keep your Client Secret private - treat it like a password
• If you suspect your credentials are compromised, regenerate them in the Spotify Dashboard
• Use environment variables instead of config files when possible

Next Steps

Once Spotify is connected, you can:

• Use commit-vibes to create commits with your current song
• Use commit-vibes --preview to test without creating commits
• Your music will automatically be included in commit messages when available