CWS CLI

A TypeScript CLI tool for managing Chrome extensions in the Chrome Web Store using the Chrome Web Store API v2.

Features

📦 Upload extension packages (.zip or .crx files)
🚀 Publish extensions with various options
📊 Check status of extensions and submissions
❌ Cancel active submissions
🎯 Manage deployment percentage for published extensions
🔧 Easy configuration with interactive setup or environment variables
🔄 CI/CD ready with environment variable support
🔍 Verbose output and dry-run mode for testing

Installation

Requirements: Node.js ≥18.0.0

Global Installation (Recommended)

npm install -g cws-manager-cli

Local Installation

npm install cws-manager-cli
npx cws-manager --help

From Source

git clone https://github.com/andyghiuta/cws-manager-cli.git
cd cws-manager-cli
npm install
npm run build
npm link

Quick Start

Configure your credentials:

cws-manager configure

Or set environment variables (see Configuration for details):

export CWS_CLIENT_ID="your-client-id"
export CWS_CLIENT_SECRET="your-secret"
export CWS_REFRESH_TOKEN="your-token"
export CWS_PUBLISHER_ID="your-publisher-id"

Upload an extension:
```
cws-manager upload <item-id> <file.zip>
```
Publish the extension:
```
cws-manager publish <item-id>
```
Check status:
```
cws-manager status <item-id>
```

Configuration

Prerequisites

Before using this CLI, you need to:

Enable the Chrome Web Store API in Google Cloud Console
Create OAuth2 credentials (Client ID and Client Secret)
Generate a refresh token for API access
Get your Publisher ID from the Chrome Web Store Developer Dashboard

Detailed Setup Steps

1. Google Cloud Console Setup

Go to Google Cloud Console
Create a new project or select an existing one
Enable the Chrome Web Store API:
- Go to "APIs & Services" > "Library"
- Search for "Chrome Web Store API"
- Click "Enable"

2. OAuth2 Credentials

Go to "APIs & Services" > "Credentials"
Click "Create Credentials" > "OAuth 2.0 Client ID"
Choose "Desktop application" as the application type
Note down the Client ID and Client Secret

3. Generate Refresh Token

You can use tools like the Google OAuth2 Playground or use https://github.com/fregante/chrome-webstore-upload-keys the refresh token:

npx chrome-webstore-upload-keys

4. Get Publisher ID

Go to Chrome Web Store Developer Dashboard
Your Publisher ID is in the URL: https://chrome.google.com/webstore/devconsole/YOUR_PUBLISHER_ID

5. Configure CLI

Run the interactive configuration:

cws-manager configure

Or create a config file manually at ~/.cws-manager-cli/config.json:

{
  "clientId": "your-client-id.apps.googleusercontent.com",
  "clientSecret": "your-client-secret",
  "refreshToken": "your-refresh-token", 
  "publisherId": "your-publisher-id"
}

Alternative: Environment Variables

As an alternative to config files, you can set configuration using environment variables. This is especially useful for CI/CD environments:

export CWS_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export CWS_CLIENT_SECRET="your-client-secret"
export CWS_REFRESH_TOKEN="your-refresh-token"
export CWS_PUBLISHER_ID="your-publisher-id"

Configuration Priority:

Config file (if it exists) - takes precedence
Environment variables (fallback when config file doesn't exist)

Environment Variables:

CWS_CLIENT_ID - Google OAuth2 Client ID
CWS_CLIENT_SECRET - Google OAuth2 Client Secret
CWS_REFRESH_TOKEN - OAuth2 Refresh Token
CWS_PUBLISHER_ID - Chrome Web Store Publisher ID

Note: All four environment variables must be set for this method to work. If any are missing, you'll need to use the config file or run cws-manager configure.

Commands

`configure`

Set up API credentials interactively.

cws-manager configure [options]

Options:
  -i, --interactive                    Interactive configuration mode (default: true)
  --client-id <id>                     Google OAuth2 client ID
  --client-secret <secret>             Google OAuth2 client secret  
  --refresh-token <token>              OAuth2 refresh token
  --publisher-id <id>                  Chrome Web Store publisher ID

`upload`

Upload a new package to an existing extension.

cws-manager upload <item-id> <file> [options]

Arguments:
  item-id                              Chrome Web Store item (extension) ID
  file                                 Path to the .zip or .crx file to upload

Options:
  -s, --skip-review                    Skip review process if possible
  -p, --publish-type <type>            Publish type: default, staged (default: "default")
  -d, --deploy-percentage <percentage> Initial deploy percentage (0-100) (default: "100")
  -a, --auto-publish                   Automatically publish after successful upload
  -w, --max-wait-time <seconds>        Maximum time to wait for upload processing (default: "300")

Examples:

# Basic upload
cws-manager upload abcdefghijklmnopqrstuvwxyz1234567890 extension.zip

# Upload and auto-publish with 50% deployment
cws-manager upload abcdefghijklmnopqrstuvwxyz1234567890 extension.zip -a -d 50

# Upload as staged (requires manual publish later)
cws-manager upload abcdefghijklmnopqrstuvwxyz1234567890 extension.zip -p staged

# Upload with custom max wait time (10 minutes)
cws-manager upload abcdefghijklmnopqrstuvwxyz1234567890 extension.zip -w 600

`publish`

Publish an extension that has been uploaded.

cws-manager publish <item-id> [options]

Arguments:
  item-id                              Chrome Web Store item (extension) ID

Options:
  -s, --skip-review                    Skip review process if possible
  -p, --publish-type <type>            Publish type: default, staged (default: "default")
  -d, --deploy-percentage <percentage> Initial deploy percentage (0-100) (default: "100")

Examples:

# Publish with default settings
cws-manager publish abcdefghijklmnopqrstuvwxyz1234567890

# Publish to 25% of users initially  
cws-manager publish abcdefghijklmnopqrstuvwxyz1234567890 -d 25

# Stage for later publishing
cws-manager publish abcdefghijklmnopqrstuvwxyz1234567890 -p staged

`status`

Get the current status of an extension.

cws-manager status <item-id> [options]

Arguments:
  item-id                              Chrome Web Store item (extension) ID

Options:
  -w, --watch                          Watch for status changes (polls every 30 seconds)  
  -i, --interval <seconds>             Poll interval in seconds when watching (default: "30")

Examples:

# Check status once
cws-manager status abcdefghijklmnopqrstuvwxyz1234567890

# Watch for changes every 60 seconds
cws-manager status abcdefghijklmnopqrstuvwxyz1234567890 -w -i 60

`cancel`

Cancel the current active submission.

cws-manager cancel <item-id>

Arguments:  
  item-id                              Chrome Web Store item (extension) ID

Example:

cws-manager cancel abcdefghijklmnopqrstuvwxyz1234567890

`deploy`

Update the deployment percentage for a published extension.

cws-manager deploy <item-id> <percentage>

Arguments:
  item-id                              Chrome Web Store item (extension) ID
  percentage                           Deployment percentage (0-100)

Example:

# Deploy to 75% of users
cws-manager deploy abcdefghijklmnopqrstuvwxyz1234567890 75

Global Options

All commands support these global options:

-c, --config <path>: Path to config file (default: ~/.cws-manager-cli/config.json)
-v, --verbose: Enable verbose output
--dry: Dry run mode (don't actually make API calls)

Examples:

# Use custom config file
cws-manager -c ./my-config.json status abcdefghijklmnopqrstuvwxyz1234567890

# Verbose output  
cws-manager -v upload abcdefghijklmnopqrstuvwxyz1234567890 extension.zip

# Test commands without making API calls
cws-manager --dry publish abcdefghijklmnopqrstuvwxyz1234567890

CI/CD Integration

This CLI is perfect for automating extension deployments in CI/CD pipelines:

GitHub Actions Example

name: Deploy Extension

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'
          
      - name: Install CWS CLI
        run: npm install -g cws-manager-cli
        
      - name: Upload & Publish Extension
        env:
          CWS_CLIENT_ID: ${{ secrets.CWS_CLIENT_ID }}
          CWS_CLIENT_SECRET: ${{ secrets.CWS_CLIENT_SECRET }}
          CWS_REFRESH_TOKEN: ${{ secrets.CWS_REFRESH_TOKEN }}
          CWS_PUBLISHER_ID: ${{ secrets.CWS_PUBLISHER_ID }}
        run: |
          cws-manager upload ${{ secrets.EXTENSION_ID }} extension.zip --auto-publish

Jenkins Example (Using config file)

pipeline {
    agent any
    
    environment {
        EXTENSION_ID = credentials('extension-id')
        CWS_CLIENT_ID = credentials('cws-client-id')
        CWS_CLIENT_SECRET = credentials('cws-client-secret')
        CWS_REFRESH_TOKEN = credentials('cws-refresh-token')
        CWS_PUBLISHER_ID = credentials('cws-publisher-id')
    }
    
    stages {
        stage('Install CLI') {
            steps {
                sh 'npm install -g cws-manager-cli'
            }
        }
        
        stage('Configure') {
            steps {
                sh '''
                    mkdir -p ~/.cws-manager-cli
                    cat > ~/.cws-manager-cli/config.json << EOF
{
  "clientId": "${CWS_CLIENT_ID}",
  "clientSecret": "${CWS_CLIENT_SECRET}",
  "refreshToken": "${CWS_REFRESH_TOKEN}",
  "publisherId": "${CWS_PUBLISHER_ID}"
}
EOF
                '''
            }
        }
        
        stage('Deploy') {
            steps {
                sh 'cws-manager upload ${EXTENSION_ID} extension.zip --auto-publish'
            }
        }
    }
}

Docker Example

FROM node:18-alpine
RUN npm install -g cws-manager-cli

ENV CWS_CLIENT_ID=""
ENV CWS_CLIENT_SECRET=""
ENV CWS_REFRESH_TOKEN=""
ENV CWS_PUBLISHER_ID=""

COPY extension.zip .
CMD ["cws", "upload", "${EXTENSION_ID}", "extension.zip", "--auto-publish"]

Shell Script Example

#!/bin/bash
# deploy-extension.sh

# Check if environment variables are set
if [[ -z "$CWS_CLIENT_ID" || -z "$CWS_CLIENT_SECRET" || -z "$CWS_REFRESH_TOKEN" || -z "$CWS_PUBLISHER_ID" ]]; then
  echo "Error: All CWS environment variables must be set"
  exit 1
fi

# Upload and publish extension
cws-manager upload "$EXTENSION_ID" extension.zip --auto-publish --deploy-percentage 25

echo "Extension deployed with 25% rollout"

API Reference

The CLI is built on top of the Chrome Web Store API v2. Here are the main API endpoints used:

Upload: POST /v2/publishers/{publisherId}/items/{itemId}:upload
Publish: POST /v2/publishers/{publisherId}/items/{itemId}:publish
Status: GET /v2/publishers/{publisherId}/items/{itemId}:fetchStatus
Cancel: POST /v2/publishers/{publisherId}/items/{itemId}:cancelSubmission
Deploy: POST /v2/publishers/{publisherId}/items/{itemId}:setPublishedDeployPercentage

Troubleshooting

Common Issues

"Config file not found"
- Run cws-manager configure to create the config file
- Or specify a config path with -c <path>
"Failed to obtain access token"
- Check that your refresh token is valid
- Ensure the Chrome Web Store API is enabled in Google Cloud Console
- Verify your OAuth2 credentials
"Upload failed: 400 Bad Request"
- Ensure the item ID exists and you have permissions
- Check that the file is a valid .zip or .crx extension package
- Verify the file size is under the 2GB limit
"HTTP 403: Forbidden"
- Check your Publisher ID is correct
- Ensure you have the right permissions for the extension
- Verify the OAuth2 scope includes https://www.googleapis.com/auth/chromewebstore

Debug Mode

Use verbose mode to see detailed API requests and responses:

cws-manager -v status your-extension-id

Use dry run mode to test commands without making actual API calls:

cws-manager --dry upload your-extension-id extension.zip

Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes and add tests
Run the build: npm run build
Run tests: npm test
Submit a pull request

Development

# Clone the repository
git clone https://github.com/andyghiuta/cws-manager-cli.git
cd cws-manager-cli

# Install dependencies  
npm install

# Build the project
npm run build

# Link for local development
npm link

# Run in development mode
npm run dev

License

MIT License - see LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.github/workflows		.github/workflows
.husky		.husky
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
commitlint.config.js		commitlint.config.js
config.example.json		config.example.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

andyghiuta/cws-manager-cli

Folders and files

Latest commit

History

Repository files navigation

CWS CLI

Features

Installation

Global Installation (Recommended)

Local Installation

From Source

Quick Start

Configuration

Prerequisites

Detailed Setup Steps

1. Google Cloud Console Setup

2. OAuth2 Credentials

3. Generate Refresh Token

4. Get Publisher ID

5. Configure CLI

Alternative: Environment Variables

Commands

configure

upload

publish

status

cancel

deploy

Global Options

CI/CD Integration

GitHub Actions Example

Jenkins Example (Using config file)

Docker Example

Shell Script Example

API Reference

Troubleshooting

Common Issues

Debug Mode

Contributing

Development

License

Related Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Languages

`configure`

`upload`

`publish`

`status`

`cancel`

`deploy`

Packages