--- updatedAt: 2026-03-30T18:23:07.000Z agentTools: projectIndex: https://docs.checkhq.com/llms.txt --- # Check CLI Leverage the full power of Check's platform from the command line. The Check CLI is a command-line interface for the Check Payroll API. Use it to query payroll data, automate workflows, and integrate Check into your scripts and CI/CD pipelines. The Check CLI is open source software, licensed under the MIT License, and hosted on GitHub in Check's [MCP Server & CLI Repository](https://github.com/check-technologies/mcp-server-check). It ships with the same repo as the MCP Server and reuses the same 270 tool functions. ## When to use the CLI vs. MCP | | Check CLI | Check MCP Server | | --------- | ------------------------------------------------- | ---------------------------------------------- | | Best for | Shell scripts, CI/CD pipelines, one-off lookups | Interactive AI workflows | | Interface | Shell commands | MCP protocol (JSON-RPC) | | Output | JSON by default, pipe through `jq` and Unix tools | AI picks the right tool and interprets results | | Auth | Flag, env var, or config | Env var (self-hosted) or OAuth (hosted) | | Overhead | Minimal — direct request/response | Requires an MCP-compatible AI client | | Debugging | See exact request and response | AI abstracts the details | ## Prerequisites * **Check API Key** — Your Check API key. For testing, use your Sandbox key. * **Python 3.10+** and the **uv** package manager Install `uv` if you don't have it: ```shell # Mac / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` * **Git** — Needed to clone the repo. Verify with `git --version`. ## Quick start Clone the repo and install dependencies: ```bash git clone https://github.com/check-technologies/mcp-server-check.git cd mcp-server-check uv sync ``` Set your API key and verify the CLI is working: ```bash export CHECK_API_KEY=your-api-key-here uv run check --help ``` To install globally (no `uv run` prefix needed): ```bash uv tool install -e . check --help ``` > 📘 **`uv run check` vs `check`** — In order to run CLI commands using `check` instead of `uv run check` install the Check CLI tool globally by running `uv tool install -e .` ## Exploring commands The CLI is organized by resource type. Use `--help` at any level to discover available commands and options: ```shell # See all top-level resource categories check --help # See all commands for a resource check companies --help check employees --help check payrolls --help # See options for a specific command check employees list --help ``` ## Command structure Commands follow a `check ` pattern: ``` check [ARGS] [OPTIONS] ``` There are 18 resource groups, each with multiple commands: | Group | Examples | | --------------------- | --------------------------------------------------------------------------- | | `companies` | `list`, `get`, `create`, `update`, `onboard`, `get-paydays` | | `employees` | `list`, `get`, `create`, `update`, `onboard`, `list-paystubs` | | `payrolls` | `list`, `get`, `create`, `approve`, `preview`, `simulate-start-processing` | | `contractors` | `list`, `get`, `create`, `update`, `onboard` | | `bank-accounts` | `list`, `get`, `create`, `delete`, `reveal-number` | | `compensation` | `list-pay-schedules`, `create-benefit`, `list-earning-codes` | | `tax` | `get-company-params`, `list-employee-elections`, `list-filings` | | `payments` | `list`, `get`, `retry`, `refund`, `cancel` | | `payroll-items` | `list`, `get`, `create`, `update`, `delete` | | `contractor-payments` | `list`, `get`, `create`, `delete` | | `external-payrolls` | `list`, `get`, `create`, `approve` | | `webhooks` | `list-configs`, `create-config`, `ping-config`, `retry-events` | | `documents` | `list-company-tax-documents`, `download-employee-tax-document` | | `components` | `create-company-run-payroll-component`, `create-employee-profile-component` | | `forms` | `list`, `get`, `render`, `validate` | | `platform` | `list-notifications`, `validate-address`, `sync-accounting` | | `workflows` | `get-company-overview`, `get-employee-snapshot`, `get-payroll-details` | | `workplaces` | `list`, `get`, `create`, `update` | ## Global options ``` --api-key TEXT Check API key (or CHECK_API_KEY env var) --env [sandbox|production] API environment (default: sandbox; or CHECK_ENV) --format [json|table] Output format (default: json) --read-only Block write operations (or CHECK_READ_ONLY) --verbose Print request details to stderr --version Show version --help Show help ``` ## Example commands ```shell # List all companies check companies list # Get a specific company check companies get com_xxxxx # List employees in table format check employees list --company com_xxxxx --format table # Preview a payroll before approving check payrolls preview prl_xxxxx # Approve a payroll check payrolls approve prl_xxxxx # Get W-4 tax parameters for an employee check tax params list --employee emp_xxxxx ``` ## Output formats The CLI outputs JSON by default. Use the `--format` flag to change the output: ```shell # Default JSON output check companies list # Table format for quick lookups check employees list --company com_xxxxx --format table ``` ## Pipe & compose JSON output makes it easy to chain with standard Unix tools like [`jq`](https://jqlang.org/manual/) : ```shell # Extract all employee IDs for a company check employees list --company com_xxxxx | jq '.results[].id' # Get a count of active employees check employees list --company com_xxxxx | jq '.results | length' # Export employee data to CSV check employees list --company com_xxxxx | jq -r '.results[] | [.id, .first_name, .last_name] | @csv' # Find all pending payrolls check payrolls list --company com_xxxxx | jq '.results[] | select(.status == "pending")' # Get details for each employee check employees list --company com_xxxxx | jq -r '.results[].id' | \ xargs -I{} check employees get {} ``` ## Parameter types | Type | Syntax | Example | | --------------- | --------------------- | ---------------------------------- | | ID (positional) | `` | `check companies get com_xxxxx` | | String | `--option value` | `--legal-name "Acme Corp"` | | Integer | `--option N` | `--limit 10` | | Boolean flag | `--flag / --no-flag` | `--active` or `--no-active` | | JSON object | `--option '{...}'` | `--address '{"line1":"123 Main"}'` | | JSON from file | `--option @file.json` | `--address @addr.json` | | JSON from stdin | `--option @-` | `echo '{}' \| check ... --data @-` | | CSV list | `--option a,b,c` | `--ids com_001,com_002` | ## Access control The CLI supports the same access control options as the MCP Server. Set these as environment variables before running commands. ```shell # Read-only mode — disables all create, update, and delete operations export CHECK_READ_ONLY=true # Limit to specific resource categories export CHECK_TOOLSETS=companies,employees # Exclude individual commands export CHECK_EXCLUDE_TOOLS=create_bank_account # Combine all three export CHECK_API_KEY=your-api-key-here export CHECK_READ_ONLY=true export CHECK_TOOLSETS=companies,employees export CHECK_EXCLUDE_TOOLS=reveal_employee_ssn ``` Available toolsets: `bank_accounts`, `companies`, `compensation`, `components`, `contractor_payments`, `contractors`, `documents`, `employees`, `external_payrolls`, `forms`, `payments`, `payroll_items`, `payrolls`, `platform`, `tax`, `webhooks`, `workflows`, `workplaces` In read-only mode, write commands are hidden from `--help` output. Filtering precedence: `exclude_tools` > `read_only` > `tools` > `toolsets`. For more details on access control options, see the [MCP Server access control documentation](https://docs.checkhq.com/docs/self-hosted). ## Switching to production By default, the CLI connects to `sandbox.checkhq.com`. To use production: ```shell # Via flag check --env production payrolls list # Via environment variable export CHECK_ENV=production check payrolls list # Or set the base URL directly export CHECK_API_BASE_URL=https://api.checkhq.com export CHECK_API_KEY=your-production-api-key ``` **Use caution in production.** Actions taken through the CLI are real — payrolls will be processed, payments will be sent, and records will be modified. Consider using `--read-only` or toolset filtering to limit what the CLI can do. ## Exit codes | Code | Meaning | | ---- | ----------------------------------------------- | | 0 | Success | | 1 | API error (4xx/5xx response) | | 2 | Usage error (missing argument, unknown command) | | 3 | Authentication error (no API key) | Error details are printed to stderr, data to stdout, so pipes work correctly even on errors. ## Examples ### Payroll workflow ```bash # Create a payroll check payrolls create \ --company com_xxxxx \ --period-start 2026-01-01 \ --period-end 2026-01-15 \ --payday 2026-01-20 # Add a payroll item check payroll-items create \ --payroll prl_xxxxx \ --employee emp_xxxxx \ --earnings '[{"amount":"5000.00","earning_code":"ec_xxxxx"}]' # Preview the payroll check payrolls preview prl_xxxxx # Approve it check payrolls approve prl_xxxxx # Simulate processing (sandbox only) check payrolls simulate-start-processing prl_xxxxx check payrolls simulate-complete-funding prl_xxxxx check payrolls simulate-complete-disbursements prl_xxxxx ``` ### Employee onboarding ```bash # Create an employee check employees create \ --company com_xxxxx \ --first-name Jane \ --last-name Doe \ --email jane@example.com \ --start-date 2026-02-01 # Onboard them check employees onboard emp_xxxxx # Check their forms check employees list-forms emp_xxxxx ``` ### Reports ```bash # Payroll journal check companies get-payroll-journal-report com_xxxxx \ --start-date 2026-01-01 --end-date 2026-03-31 # Tax liabilities check companies get-tax-liabilities-report com_xxxxx \ --start-date 2026-01-01 --end-date 2026-03-31 # W-2 preview check companies get-w2-preview-report com_xxxxx --year 2025 ``` ### Webhooks ```bash # List webhook configs check webhooks list-configs # Create a webhook check webhooks create-config \ --url https://example.com/webhooks \ --environment sandbox # Test it check webhooks ping-config whc_xxxxx ```