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 linkAfter linking, the greenshades command will be available globally.
- Copy
.env.exampleto.envand fill in your credentials:
cp .env.example .envGREENSHADES_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 loginYou'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 statusgreenshades 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 fieldsgreenshades 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 rungreenshades 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 codesgreenshades department list # List all departments
greenshades department details <code> # Get a department by codegreenshades locations list # List all work locations
greenshades locations details <code> # Get a location by codegreenshades positions list # List all positions
greenshades positions details <code> # Get a position by code
greenshades positions worker-compensation-codes # List worker compensation codesgreenshades placements list # List all placements
greenshades placements employee <employeeId> # Get placements for an employee
greenshades placements details <placementId> # Get a single placementgreenshades classes list # Get all employee classes
greenshades classes details <class-code> # Get a single employee classgreenshades 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 employeegreenshades payruns list # Get all payruns for the workspace
greenshades payruns info <payrun-id> # Get earning codes for a specific payrungreenshades 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 reportgreenshades 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 IDgreenshades 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 subscriptionAfter 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