Kick CLI

kick is the command-line interface for Kick. It talks to the same Kick API used by the web app and authenticates with a Kick personal access token (PAT).

Install

npm install -g @kickfinance/cli
kick --help

You can also run it without a global install:

npx @kickfinance/cli --help

The package installs a single binary named kick.

Sign In

For interactive use, run:

kick login

The CLI opens a browser authorization page, asks you to approve a personal access token, and stores the token in your OS keychain. If the keychain is not available, it falls back to ~/.config/kick/credentials with file mode 0600.

For CI or scripted use, provide a PAT explicitly:

export KICK_PAT=kick_pat_...
kick whoami

Token lookup order is:

1. --token <value>
2. KICK_PAT
3. KICK_API_TOKEN (deprecated)
4. OS keychain from kick login
5. ~/.config/kick/credentials

Common Commands

kick whoami
kick workspaces list
kick --workspace <workspace-id> transactions find --since 2026-01-01
kick --workspace <workspace-id> reports profit-loss --entity 123 --start-date 2026-01-01 --end-date 2026-01-31 --output json
kick tools list
kick logout

Use profiles for multiple environments:

kick config set profiles.dev.apiBaseUrl http://localhost:8000/api
kick config set defaultProfile dev
kick --profile dev whoami

The default production API base URL is https://use.kick.co/api.

Output

The CLI is designed for both humans and automation:

• Data is written to stdout.
• Diagnostics, progress messages, and errors are written to stderr.
• --output auto prints tables in a terminal and structured output when piped.
• --output json, --output json-compact, --output yaml, and --output table are available when you need a stable format.

Examples:

kick transactions find --limit 10
kick transactions find --output json | jq '.[0].id'

List commands are bounded. Use --limit, --cursor, and --fields where available to control result size and shape.

The shared result-size contract lives in agentTools/core: tools own fields, filters, search, limit, cursor pagination, default projection, and output shape. CLI commands should only map flags and payload files into that core input contract, render output, and print pagination hints. They should not hide a second truncation layer behind successful JSON output.

Agent Tools

The CLI exposes the complete PAT-allowed core agent-tools catalog:

kick tools list
kick tools schema transactions_find
kick --workspace <workspace-id> tools run transactions_find --input-json '{"limit":10}'

kick tools run defaults workspaceId from --workspace or the active profile when the selected tool accepts workspaceId and the input omits it. Mutation tools are preview-first: run once without confirmationToken, inspect the preview response, then rerun with the returned token.

kick tools list and kick tools schema inspect the local PAT-allowed core catalog packaged with the CLI. Actual tool execution still goes through the Kick API, so the server may reject a call based on token scope, feature flags, plan capabilities, workspace grants, or controller permissions.

--input-json and --input-file provide the selected core tool's input object. Use kick tools schema <toolName> to inspect supported inputs such as cursor, limit, fields, filters, and payload fields.

Focused human workflows are also available as first-class command groups:

kick categories list
kick classes create --label Consulting
kick counterparties merge --from <counterparty-id> --into <counterparty-id>
kick accounting accounts list --entity-id 123
kick entities get-address --entity-id 123

Long-tail or schema-heavy operations remain available through kick tools schema and kick tools run.

Exit Codes

| Code | Meaning | | ---- | ------------------------------------- | | 0 | Success | | 1 | Generic failure | | 2 | Usage error | | 3 | Network error | | 4 | Authentication or authorization error | | 5 | Not found | | 6 | Rate limited | | 130 | Interrupted |

Security Notes

Kick CLI requests go through the normal Kick API authorization path. PAT scope, workspace access, and backend permissions are enforced server-side.

Use read-only PATs for lookup-only automation. Use short expirations for tokens created for CI or agent workflows, and revoke tokens with kick logout or from Kick settings when they are no longer needed.

Versioning

The CLI follows semantic versioning for command names, global flags, documented exit codes, and machine-readable output shapes.

License

Kick CLI is licensed under the Apache License, Version 2.0. See LICENSE for details.