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

$3

``bash
npm install -g cws-manager-cli
`

$3

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

$3

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

Quick Start

1. Configure your credentials:
`bash
cws-manager configure
`

Or set environment variables (see Configuration for details):
`bash
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"
`

2. Upload an extension:
`bash
cws-manager upload
`

3. Publish the extension:
`bash
cws-manager publish
`

4. Check status:
`bash
cws-manager status
`

Configuration

$3

Before using this CLI, you need to:

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

$3

#### 1. Google Cloud Console Setup

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

#### 2. OAuth2 Credentials

1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth 2.0 Client ID"
3. Choose "Desktop application" as the application type
4. 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:

`bash
npx chrome-webstore-upload-keys
`

#### 4. Get Publisher ID

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

#### 5. Configure CLI

Run the interactive configuration:

`bash
cws-manager configure
`

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

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

$3

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

`bash
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:
1. Config file (if it exists) - takes precedence
2. 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

$3

Set up API credentials interactively.

`bash
cws-manager configure [options]

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

$3

Upload a new package to an existing extension.

`bash
cws-manager upload [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 Publish type: default, staged (default: "default")
-d, --deploy-percentage Initial deploy percentage (0-100) (default: "100")
-a, --auto-publish Automatically publish after successful upload
-w, --max-wait-time Maximum time to wait for upload processing (default: "300")
`

Examples:
`bash


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
`

$3

Publish an extension that has been uploaded.

`bash
cws-manager publish [options]

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

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

Examples:
`bash


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
`

$3

Get the current status of an extension.

`bash
cws-manager status [options]

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

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

Examples:
`bash


Check status once

cws-manager status abcdefghijklmnopqrstuvwxyz1234567890

Watch for changes every 60 seconds

cws-manager status abcdefghijklmnopqrstuvwxyz1234567890 -w -i 60
`

$3

Cancel the current active submission.

`bash
cws-manager cancel

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

Example:
`bash
cws-manager cancel abcdefghijklmnopqrstuvwxyz1234567890
`

$3

Update the deployment percentage for a published extension.

`bash
cws-manager deploy

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

Example:
`bash


Deploy to 75% of users


cws-manager deploy abcdefghijklmnopqrstuvwxyz1234567890 75
`

Global Options

All commands support these global options:

- -c, --config : 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:
`bash


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:

$3

`yaml
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
`

$3

`groovy
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'
}
}
}
}
`

$3

`dockerfile
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"]
`

$3

`bash
#!/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

$3

1. "Config file not found"
- Run cws-manager configure to create the config file
- Or specify a config path with -c

2. "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

3. "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

4. "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

$3

Use verbose mode to see detailed API requests and responses:

`bash
cws-manager -v status your-extension-id
`

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

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




Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Run the build: npm run build
5. Run tests: npm test
6. Submit a pull request

Development

`bash


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.

Related Links

- Chrome Web Store API Documentation
- Chrome Extension Development Guide
- Google Cloud Console
- Chrome Web Store Developer Dashboard