A command-line interface for interacting with the Greenshades HR/Payroll API. Query employees, paystubs, payroll settings, departments, positions, placements, and more directly from your terminal.
- Node.js (ES modules support required)
- A Greenshades account with API access (OAuth2 credentials)
git clone <repo-url> cd gs-cli npm install npm link
After linking, the greenshades command will be available globally.
- Copy
.env.exampleto.envand fill in your credentials:
cp .env.example .env
GREENSHADES_CLIENT_ID=your_client_id GREENSHADES_CLIENT_SECRET=your_client_secret GREENSHADES_WORKSPACE_ID=your_workspace_id GREENSHADES_API_SCOPE=GO.Api.COR.read GO.Api.PAY.read GO.Api.PAY.Setup.read GO.Api.PAY.PayRuns.read GO.Api.PAY.Reporting.read
- Authenticate:
greenshades auth login
You'll be prompted for your Client ID, Client Secret, and Workspace ID (defaults to .env values). On success, the token and workspace ID are stored locally for subsequent commands.
- Verify setup:
greenshades test
greenshades auth statusgreenshades auth login # Authenticate and save credentials greenshades auth logout # Clear stored credentials greenshades auth status # Show current authentication status
greenshades employee list [--nativeId <id>] # List all employees, optionally filtered greenshades employee pull <employeeId> # Get a single employee by ID greenshades employee dependents <employeeId> # Get employee dependents greenshades employee contacts <employeeId> # Get employee contacts greenshades employee customFields <employeeId> # Get employee custom fields
greenshades paystubs list # List paystubs from the last 2 days greenshades paystubs details <payRecordId> # Get a single paystub greenshades paystubs employee <employeeId> # Get all paystubs for an employee greenshades paystubs payrun <payRunId> # Get all paystubs for a pay run
greenshades settings pay-details <employeeId> # Direct deposit settings greenshades settings earn-codes <employeeId> # Earning codes greenshades settings tax-details <employeeId> # Tax information greenshades settings pay-schedule <employeeId> # Pay schedule greenshades settings time-off <employeeId> # Time-off balances greenshades settings benefits <employeeId> # Benefit codes greenshades settings deductions <employeeId> # Deduction codes
greenshades department list # List all departments greenshades department details <code> # Get a department by code
greenshades locations list # List all work locations greenshades locations details <code> # Get a location by code
greenshades positions list # List all positions greenshades positions details <code> # Get a position by code greenshades positions worker-compensation-codes # List worker compensation codes
greenshades placements list # List all placements greenshades placements employee <employeeId> # Get placements for an employee greenshades placements details <placementId> # Get a single placement
greenshades classes list # Get all employee classes greenshades classes details <class-code> # Get a single employee class
greenshades custom list # Get all custom fields greenshades custom details <field-id> # Get a single custom field greenshades custom employee <employee-id> # Get all custom fields for a specific employee
greenshades payruns list # Get all payruns for the workspace greenshades payruns info <payrun-id> # Get earning codes for a specific payrun
greenshades report timeoff-balances # Get all time-off balances for the workspace (exports to JSON) greenshades report timeoff-balances -o table # View time-off balances output format as a table greenshades report benefits-deductions # Get benefits and deductions report
greenshades logs list # Get all request logs (defaults to the last 24 hours) greenshades logs list -s <date> -e <date> # Get request logs for a specific date range (YYYY-MM-DD) greenshades logs details <request-id> # Get a single request log by its ID
greenshades webhooks list # List all webhook subscriptions greenshades webhooks details <webhookId> # Get a webhook subscription by ID greenshades webhooks create <event-name> <callback-url> [hmac-key] # Create a new webhook subscription greenshades webhooks delete <id> # Delete a webhook subscription greenshades webhooks subscribe <id> <event-name> # Add an event to an existing subscription greenshades webhooks tap <id> <event-name> # Tap into an event for an existing subscription greenshades webhooks unsubscribe <id> <event-name> # Remove an event from an existing subscription
After login, credentials are persisted locally via conf:
| Platform | Path |
|---|---|
| Linux | ~/.config/gs-cli/config.json |
| macOS | ~/Library/Preferences/gs-cli/config.json |
| Windows | %APPDATA%\gs-cli\config.json |
The stored config contains the access token and workspace ID. Treat this file as sensitive.
ISC