Awaken CLI

Command line tools for working with Awaken clients, transaction labels, and wallet transaction workflows.

Installation

Install the published package from npm:

npm install -g @awakentax/cli

Verify the executable is available:

awaken help

Node.js 18 or newer is required.

Local Development

From this repository:

npm install
npm run build
npm link

Run the TypeScript source directly during development:

npm run dev -- help

Authentication

The CLI authenticates with an Awaken API key and stores credentials at:

~/.awaken/credentials.json

The credentials file is written with 0600 permissions.

Interactive Login

awaken login

You will be prompted for an API key and, optionally, a default client ID.

You can also pass values non-interactively:

awaken login --api-key <apiKey> --client-id <clientId>

Save Credentials Directly

awaken config <apiKey> [clientId]

Equivalent flag form:

awaken config --api-key <apiKey> --client-id <clientId>

API URL

By default, the CLI connects to:

https://api.awaken.tax

Override the API URL with --api-url when running login or config:

awaken config --api-key <apiKey> --client-id <clientId> --api-url http://localhost:3000

You can also set one of these environment variables:

AWAKEN_API_URL=http://localhost:3000
API_URL=http://localhost:3000

The CLI sends GraphQL requests to /graphql under the configured API URL.

Status and Logout

Show saved configuration:

awaken status

Remove saved credentials:

awaken logout

Output Format

Most commands print pretty-formatted JSON to stdout. Errors are printed to stderr and the process exits with a non-zero status code.

Client Selection

Commands that operate on client data use the following precedence:

1. --client-id <clientId> passed to the command
2. The default client ID saved by awaken login or awaken config
3. The active client returned by the Awaken API for the authenticated user

Show the resolved active/default client:

awaken active-client

Set the authenticated user's active Awaken client:

awaken set-active-client <clientId>

Equivalent flag form:

awaken set-active-client --client-id <clientId>

Commands

awaken help

Print command help.

awaken
awaken help

awaken labels

List Awaken label options.

awaken labels

The response includes:

• total
• labels

awaken type-options

List valid transaction type labels for one transaction.

awaken type-options <transactionId>

Equivalent flag form:

awaken type-options --transaction-id <transactionId>

Options:

| Option | Description | | --- | --- | | --client-id <clientId> | Override the saved/default active client. |

The response includes:

• clientId
• transactionId
• message
• labels

awaken transactions

List client transactions with common filters.

awaken transactions --wallet-address <address> --limit 25

Options:

| Option | Description | | --- | --- | | --client-id <clientId> | Override the saved/default active client. | | --wallet-address <address> | Filter by from/to wallet address. | | --amount-filter-operator <operator> | Pass an Awaken amount filter operator through to the API. | | --amount-filter-value <value> | Pass an Awaken amount filter value through to the API. | | --amount-greater-than <number> | Locally keep only transactions whose USD amount is greater than this value. | | --amount-less-than <number> | Locally keep only transactions whose USD amount is less than this value. | | --start-date YYYY-MM-DD | Filter transactions on or after this date. | | --end-date YYYY-MM-DD | Filter transactions on or before this date. | | --labels <label[,label...]> | Filter by one or more labels. May be passed more than once. | | --providers <provider[,provider...]> | Filter by one or more providers. May be passed more than once. | | --search <text> | Search transactions. | | --limit <integer> | Number of transactions to request. | | --page <integer> | Page number to request. | | --sort-by <field> | Sort field to pass through to the API. | | --ascending <true\|false> | Sort ascending or descending. | | --include-hidden <true\|false> | Include hidden transactions. | | --include-spam <true\|false> | Include spam transactions. | | --reviewed <true\|false> | Filter by reviewed state. | | --only-transaction-ids <id[,id...]> | Restrict to specific transaction IDs. May be passed more than once. |

Examples:

awaken transactions --wallet-address 0xabc123 --limit 25
awaken transactions --start-date 2026-01-01 --end-date 2026-01-31
awaken transactions --labels "Fee expense deduction,Transfer" --reviewed false
awaken transactions --only-transaction-ids txn_1,txn_2

The response includes:

• clientId
• totalMatchedByAwaken
• totalReturned
• transactions

Transaction objects include:

• id
• title
• labelUsed
• provider
• priceCents
• createdAt
• txnHash
• isHidden
• notes
• reviewStatus
• status

awaken label-transactions

Apply a label to one or more transactions, optionally with notes.

awaken label-transactions --transaction-ids <id> --label "Fee expense deduction"

Options:

| Option | Description | | --- | --- | | --client-id <clientId> | Override the saved/default active client. | | --transaction-ids <id[,id...]> | Required. Transaction IDs to update. May be passed more than once. | | --label <label> | Label to apply. Required unless --wipe-label true is used. | | --notes <notes> | Notes to save with the label update. | | --wipe-label <true\|false> | Remove the label instead of applying one. |

Examples:

awaken label-transactions --transaction-ids txn_1 --label "Fee expense deduction"
awaken label-transactions --transaction-ids txn_1,txn_2 --label Transfer --notes "Reviewed by CLI"
awaken label-transactions --transaction-ids txn_1 --wipe-label true

Limits:

• Up to 50 transaction IDs per mutation.
• --label must be omitted when --wipe-label true is used.

The response includes:

• clientId
• updatedCount
• transactions

awaken split-transaction

Split one or more transfer IDs out of a base transaction.

awaken split-transaction <transactionId> --transfer-ids <transferId>

Equivalent flag form:

awaken split-transaction --transaction-id <transactionId> --transfer-ids <transferId>

Options:

| Option | Description | | --- | --- | | --client-id <clientId> | Override the saved/default active client. | | --transfer-ids <id[,id...]> | Required. Transfer IDs to separate. May be passed more than once. |

Examples:

awaken split-transaction txn_1 --transfer-ids transfer_1
awaken split-transaction txn_1 --transfer-ids transfer_1,transfer_2

Limits:

• Up to 200 transfer IDs per split.

The response includes:

• clientId
• transaction

awaken split-wallet-fees

Find visible wallet transfers, split them out of matching transactions, and label the base fee transactions.

By default this command is a dry run. Use --apply to make changes.

Dry run:

awaken split-wallet-fees <walletAddress> --dry-run

Apply changes:

awaken split-wallet-fees <walletAddress> --apply

Options:

| Option | Description | | --- | --- | | --client-id <clientId> | Override the saved/default active client. | | --fee-label <label> | Label to apply to base fee transactions. Defaults to Fee expense deduction. | | --notes <notes> | Notes to save when labeling base fee transactions. | | --limit <integer> | Number of wallet transactions to inspect. Capped at 25. | | --include-no-fee-transactions | Also process transactions that do not currently have fee entries. | | --apply | Perform the split and label mutations. Omit this flag for dry-run mode. |

Examples:

awaken split-wallet-fees 0xabc123
awaken split-wallet-fees 0xabc123 --limit 10
awaken split-wallet-fees 0xabc123 --fee-label "Fee expense deduction" --apply
awaken split-wallet-fees 0xabc123 --include-no-fee-transactions --apply

Dry-run responses include:

• dryRun
• clientId
• candidateCount
• candidates

Apply responses include:

• dryRun
• clientId
• updatedCount
• failedCount
• results
• failures

Limits and behavior:

• The command inspects at most 25 transactions per run.
• Transactions with more than 200 visible transfers are refused.
• Hidden transfers are ignored.
• Without --include-no-fee-transactions, only transactions with existing fee entries are candidates.
• The command continues processing other candidates if one split or label mutation fails.

Aliases

The CLI supports shorter command aliases and MCP-style command names.

| Alias | Command | | --- | --- | | get-active-client | active-client | | awaken_get_active_client | active-client | | awaken_set_active_client | set-active-client | | list-labels | labels | | awaken_list_labels | labels | | transaction-type-options | type-options | | awaken_get_transaction_type_options | type-options | | list-transactions | transactions | | awaken_list_transactions | transactions | | label | label-transactions | | awaken_label_transactions | label-transactions | | split | split-transaction | | awaken_split_transaction | split-transaction | | fee-split-label | split-wallet-fees | | awaken_split_wallet_transactions_and_label_fees | split-wallet-fees |

Argument Rules

Flags can be passed with a space or equals sign:

awaken transactions --limit 25
awaken transactions --limit=25

List flags accept comma-separated values and may also be passed more than once:

awaken transactions --labels Transfer,Trade
awaken transactions --labels Transfer --labels Trade

Boolean flags accept:

• true, 1, yes
• false, 0, no

Some commands also use presence flags. For example, --apply on split-wallet-fees is enabled by the presence of the flag.

Dates must use YYYY-MM-DD format.

Validation Limits

| Input | Limit | | --- | --- | | --labels | 50 values | | --providers | 50 values | | --only-transaction-ids | 50 values | | --transaction-ids for label-transactions | 50 values | | --transfer-ids for split-transaction | 200 values | | --limit for split-wallet-fees | 25 transactions |

--amount-greater-than must be less than --amount-less-than when both are provided.

Troubleshooting

No Saved Credentials

If you see:

No saved credentials found. Run `awaken login` or `awaken config <apiKey> [clientId]`.

Run:

awaken login

No Active Client

If you see:

No active Awaken client found. Pass --client-id or run `awaken config <apiKey> [clientId]`.

Pass a client ID explicitly:

awaken transactions --client-id <clientId>

Or save one as your default:

awaken config <apiKey> <clientId>

Local API Testing

Point the CLI at a local Awaken API:

awaken config <apiKey> <clientId> --api-url http://localhost:3000

Confirm the resolved GraphQL URL:

awaken status

npm Install Issues After Publishing

If npm recently published a new package version but install commands do not see it yet, check npm metadata:

npm view @awakentax/cli

If your npm client is filtering out fresh versions, check:

npm config get before

Unset it if needed:

npm config delete before

Development Scripts

| Script | Description | | --- | --- | | npm run build | Compile TypeScript into dist. | | npm run dev -- <command> | Run the CLI from TypeScript with ts-node. | | npm run prepare | Build before packing or publishing. |

Publishing

Build and publish the package:

npm run build
npm publish --access public

The npm package includes:

• dist
• README.md

The package exposes the awaken executable.