Session-Start Flags

Every input to createApyxClient is reachable as a CLI flag. Pass them on apyx repl or on any contract subcommand — they’re shared. Useful for one-session deviations from your config: swap in a paid RPC, point at a fork, override an address.

Flag table
Where overrides apply
Common patterns
Bigint flag values (for contract subcommands)
Source-of-truth

Flag table

Flag	Maps to	Notes
`--profile <name>`	which profile to load	Default: `defaultProfile` from the merged config. Errors `Unknown profile` if not present.
`--rpc-url <url>`	`profile.rpcUrl`	Any URL viem’s `http()` accepts.
`--chain ethereum\|base`	`profile.chain`	Two values today — see Supported Chains.
`--key-path <path>`	`profile.signer.keyPath`	Replaces the file the local-key signer reads. Implies `signer.type = "key"`.
`--address-apxusd <0x…>`	`addresses.apxUSD`	Override at construction. Must pass `viem.isAddress(strict)`.
`--address-apyusd <0x…>`	`addresses.apyUSD`	Override at construction.
`--address-rate-view <0x…>`	`addresses.apyUSDRateView`	Override at construction. Pass to enable the rate-view module on a chain that doesn’t natively have one.

Each flag maps to exactly one field on createApyxClient’s config. The CLI feeds an overrides struct in, and the SDK does its usual validation + freezing.

Where overrides apply

Overrides are session-start only. For apyx repl, they apply to the initial banner — but a mid-session .env <profile> swap reverts to the new profile’s own values.

sequenceDiagram
  participant User
  participant CLI as apyx repl
  participant SDK as createApyxClient
  User->>CLI: apyx repl --rpc-url $PRIVATE_RPC
  CLI->>CLI: load merged config
  CLI->>CLI: apply overrides from flags
  CLI->>SDK: { ... rpcUrl: $PRIVATE_RPC ... }
  SDK-->>CLI: ApyxClient
  CLI-->>User: banner: rpc: $PRIVATE_RPC (overridden)
  User->>CLI: .env base
  CLI->>CLI: drop overrides, reload base profile from config
  CLI->>SDK: createApyxClient with base profile defaults
  CLI-->>User: banner: rpc: https://mainnet.base.org (no override)

For non-interactive subcommands (every page under Contract Commands), overrides apply for that single invocation only.

Common patterns

Drop in a paid RPC for one session

apyx repl --rpc-url 'https://eth-mainnet.g.alchemy.com/v2/SECRET'

The banner reflects the override:

rpc:     https://eth-mainnet.g.alchemy.com/v2/SECRET (overridden)

The config file is untouched.

Switch chain for one command

apyx apyUSD exchange-rate --chain base --rpc-url https://mainnet.base.org

Useful in one-liners where you don’t want to touch the active profile.

Test against an anvil fork

apyx repl \
  --rpc-url http://127.0.0.1:8545 \
  --chain ethereum \
  --address-apyusd 0xRedeployed...  # if the fork redeployed apyUSD

The same flags drive the e2e suite — see E2E testing.

Use a different key file ad-hoc

apyx repl --key-path ~/.apyx/keys/treasury

Combined with a clean keyless config, this is a workable pattern for multi-account workflows: keep one read-only profile, point --key-path at whichever account you want to act as.

Bigint flag values (for contract subcommands)

Bigint args (--amount, --shares, --assets, etc.) are not session-start flags but they share the same parser. Accepted forms:

Form	Example	Result
Plain digits	`1234`	`1234n`
Underscore separators	`1_000_000`	`1000000n`
Scientific notation	`1e18`	`1000000000000000000n`
Hex literal	`0xff`	`255n`

Floats are rejected. Use the preview methods (apyUSD preview-deposit, apyUSD convert-to-shares, etc.) when you need decimals-to-raw conversion.

Source-of-truth

The flag list lives in the CLI dispatch under src/cli/. Adding a new field to createApyxClient should land alongside the matching flag — flag parity is a hard rule, not a nice-to-have.

Keyboard shortcuts

@koed_jang/apyx-sdk