Monocle CLI - upload source maps and manage your Monocle projects
CLI for Monocle - upload source maps to enable readable stack traces in your error monitoring.
``bash`
npm install -g @monocle.sh/clior use npx
npx @monocle.sh/cli sourcemaps upload ...
Upload source maps after your build process:
`bash`
monocle-cli sourcemaps upload \
--api-key=mk_live_xxx \
--release=v1.2.3 \
./dist/*/.map
With environment variable:
`bash`
MONOCLE_API_KEY=mk_live_xxx monocle-cli sourcemaps upload \
--release=$(git rev-parse HEAD) \
./dist/*/.map
| Option | Description | Default |
| --------------------- | -------------------------------------------------- | ------------------------ |
| --api-key | Monocle API key (or set MONOCLE_API_KEY env var) | - |--release
| | Release version (e.g., v1.2.3 or git SHA) | - |--url
| | Monocle API URL | https://api.monocle.sh |--dry-run
| | Show what would be uploaded without uploading | false |
The release identifier links exceptions to their source maps. It must match the serviceVersion configured in your Monocle agent:
`typescript`
// config/monocle.ts
export default defineConfig({
serviceVersion: env.get('APP_VERSION'), // e.g., "v1.2.3" or git SHA
})
Best practices:
- Use git commit SHA for precise matching: $(git rev-parse HEAD)v1.2.3
- Use semver for human-readable releases:
- Must match exactly between upload and runtime config
`yaml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Upload Source Maps
run: |
npx @monocle.sh/cli sourcemaps upload \
--api-key=${{ secrets.MONOCLE_API_KEY }} \
--release=${{ github.sha }} \
./dist/*/.map
- name: Deploy
run: # your deploy command
`
`yaml`
deploy:
stage: deploy
script:
- npm ci
- npm run build
- npx @monocle.sh/cli sourcemaps upload
--api-key=$MONOCLE_API_KEY
--release=$CI_COMMIT_SHA
./dist/*/.map
- # your deploy command
`yaml
version: 2.1
jobs:
deploy:
docker:
- image: cimg/node:20.0
steps:
- checkout
- run: npm ci
- run: npm run build
- run:
name: Upload Source Maps
command: |
npx @monocle.sh/cli sourcemaps upload \
--api-key=$MONOCLE_API_KEY \
--release=$CIRCLE_SHA1 \
./dist/*/.map
- run: # your deploy command
`
For AdonisJS projects using tsc and Node.js (no bundler):
`json`
{
"compilerOptions": {
"sourceMap": true,
"inlineSources": true,
"sourceRoot": "/"
}
}
`typescript
// config/monocle.ts
import env from '#start/env'
export default defineConfig({
serviceVersion: env.get('APP_VERSION'),
})
`
`bash`In your CI/CD or .env
APP_VERSION=$(git rev-parse HEAD)
`yamlGitHub Actions example
- name: Build
run: node ace build
- name: Upload Source Maps
run: |
npx @monocle.sh/cli sourcemaps upload \
--api-key=${{ secrets.MONOCLE_API_KEY }} \
--release=${{ github.sha }} \
./build/*/.map
- name: Deploy
run: # rsync, docker push, etc.
`
The --release value must match APP_VERSION used at runtime.
Source maps can expose your source code. Delete them after upload:
`yaml
- name: Upload Source Maps
run: npx @monocle.sh/cli sourcemaps upload ...
- name: Remove source maps from build
run: find ./build -name "*.map" -delete
- name: Deploy
run: # deploy without .map files
`
- Check that your build generates .map files--dry-run
- Verify your glob patterns match the output location
- Try using to see what would be matched
- Verify your API key is correct
- Ensure the API key has write permissions for source maps
- Check that MONOCLE_API_KEY environment variable is set correctly
- Ensure the --release value matches serviceVersion` in your Monocle agent config
- Verify source maps were uploaded successfully
- Check that the source map filenames match the ones referenced in your minified code