Skip to content

CLI Client Guide

Use this page after Install. It focuses on day-to-day CLI-client use, not package installation.

Role Of The CLI Client

tidal is the API-backed CLI client. It does not own the shared database. It reads and prepares actions through the control-plane API, then signs and sends transactions locally.

That split matters:

  • the server owns shared state and audit history
  • the CLI client owns private-key access

First-Time Setup

At minimum, put the API auth values in ~/.tidal/cli/.env or export them in your shell:

export TIDAL_API_BASE_URL=https://api.tidal.wavey.info
export TIDAL_API_KEY=<cli-client-api-key>

If you are using https://api.tidal.wavey.info, API keys are provided by wavey on request.

You can also pass --api-base-url and --api-key per command, but ~/.tidal/cli/.env is the normal path.

Client-side config values that are often useful in ~/.tidal/cli/config.yaml:

  • tidal_api_base_url
  • tidal_api_request_timeout_seconds
  • prepared_action_max_age_seconds
  • txn_max_gas_limit for API-prepared auction management actions such as enable-tokens
  • shared RPC timeout settings if you also do local prepare/send work

For API-backed tidal workflows, prepared kick behavior comes from the server's tracked config/server.yaml, not the workstation.

That means:

  • editing local ~/.tidal/cli/config.yaml does not change the server-side kick: policy
  • edit config/server.yaml on the server checkout if you want shared prepare behavior to change
  • the authoritative pricing, ignore, and cooldown rules live under kick: in that file

Wallet Configuration

Transaction-sending commands load the signer from keystore configuration:

  • TXN_KEYSTORE_PATH: default keystore path
  • TXN_KEYSTORE_PASSPHRASE: default keystore password
  • --keystore: explicit keystore path override
  • --password-file: file containing the keystore password

The keystore secrets themselves usually live in ~/.tidal/cli/.env:

  • TXN_KEYSTORE_PATH
  • TXN_KEYSTORE_PASSPHRASE

Example:

tidal kick run

The sender address is inferred from the resolved keystore.

Read-Only Workflows

Inspect recent kicks:

tidal logs kicks
tidal logs kicks --status CONFIRMED
tidal logs kicks --source 0xSource

Inspect scan history:

tidal logs scans

Inspect one historical run:

tidal logs show <run_id>

Inspect current kick candidates:

tidal kick inspect
tidal kick inspect --source-type fee-burner
tidal kick inspect --auction 0xAuction
tidal kick inspect --show-all

Kick Workflow

Run

tidal kick run

The CLI will:

  1. inspect candidates
  2. prepare the next exact candidate through the API
  3. show a confirmation summary
  4. sign locally
  5. send locally
  6. report broadcast and receipt data back to the API

Because preparation happens through the API, the confirmation panel reflects server-side config/server.yaml policy. The client also enforces a local age limit for prepared transactions. If you wait longer than prepared_action_max_age_seconds before sending, that prepared transaction is skipped and you need to re-run.

For unattended execution:

tidal kick run --no-confirmation

For timer or service execution:

tidal kick run --headless

Headless mode skips confirmation, emits compact line-oriented logs, keeps preparing and sending the current ready queue until it is cleared, skipped, or blocked, and exits successfully for normal no-op outcomes.

Useful flags:

  • --limit: cap how many candidates are considered
  • --source-type: strategy or fee-burner
  • --source: target one source address
  • --auction: target one auction
  • --min-usd-value: override the server txn_usd_threshold for this inspect or run
  • --no-confirmation: skip interactive confirmation
  • --headless: use unattended service-mode output, drain the ready queue, and use no-op success exits
  • --verbose: show more diagnostic detail
  • --no-require-curve: relax Curve quote strictness for this run

Auction Workflows

Deploy an auction

tidal auction deploy \
  --want 0xWant \
  --receiver 0xReceiver \
  --starting-price 1234

Enable auction tokens

tidal auction enable-tokens 0xAuction
tidal auction enable-tokens 0xAuction --extra-token 0xToken
tidal auction enable-tokens 0xAuction --extra-token 0xTokenA --extra-token 0xTokenB

Settle an active auction

tidal auction settle 0xAuction
tidal auction settle 0xAuction --token 0xActiveToken
tidal auction settle 0xAuction --sweep

Confirmations And Warnings

The kick confirmation view separates:

  • auction details: sell amount, quoted output, start/min prices, pricing profile
  • send details: sender, gas estimate, gas limit, base fee, max fee

One important warning compares:

  • the live quote output amount
  • against the evaluated spot output implied by cached sell-token USD value and a just-in-time want-token USD price

The threshold is controlled by txn_quote_spot_warning_threshold_pct.

See Pricing for the exact formula.

Failure Modes To Expect

Common CLI client-facing failures:

  • curve quote unavailable: the fresh quote succeeded overall, but Curve did not provide a usable route and strict Curve mode was enabled
  • below threshold on live balance: cached shortlist value looked large enough, but the current on-chain balance does not
  • database is locked; retry the request: the server hit SQLite write contention
  • API 401: invalid or missing bearer token

When To Use tidal-server Instead

Use tidal-server only when you are operating the server itself:

  • database migration
  • scan execution
  • API serving
  • API key management

For kick, auction, and log workflows, use tidal even if you are standing on the server host. Point it at the local API and keep the keystore local to that machine.

Command Reference

Use these pages when you need exact command shapes or flag guidance: