Skip to content
Candle candle docs

CLI quick start and FAQ

Install the CLI, create a vault, and understand what you are holding. This page is the short path and the questions people actually ask on the first run. The Candle CLI page is the full reference: every command, every flag, and the reasoning behind the vault’s design.

Install

Section titled “Install”

macOS 13 (Ventura) or later, or Linux:

curl -fsSL https://candle.tv/install.sh | bash

or with Homebrew:

brew install candledottv/tap/candle

On macOS 12 or earlier the release binaries will not run; use the npm package instead, which needs Node 18 or later:

npm i -g @candledottv/cli

Then confirm the install and let the CLI check its own setup:

candle --version
candle doctor

If you want API access as well, candle setup runs the whole thing as one wizard: authorize this device in the browser, create a key, and verify it works.

Your first vault

Section titled “Your first vault”

The vault holds keys on your machine, encrypted. Five commands, in order.

candle vault init

It prints eight words. Those eight words are your vault passphrase. It is shown once; this CLI keeps no copy and cannot recover it. Save it in your password manager or on paper. If you lose it, your 24-word recovery phrase is the way back in. Prefer your own passphrase? candle vault init --own-passphrase takes 16 characters or more instead.

candle vault phrase show

This prints 24 words: your recovery phrase. Write it on paper. This is the step that matters more than any other on this page, and the reason is in the next section.

candle vault new-key --chain solana --label main

Derives your first key and prints its address. Nothing touches a chain and no funds are involved.

candle vault backup --to /Volumes/<your drive>/candle-vault.enc

Copies the vault and verifies the copy in full, all eight steps. A backup that is merely copied is not a backup, so this one is decrypted and re-derived before it is called good.

candle vault list

Opens the vault and lists what it holds: one line per key, with its address, label, role and derivation. candle vault status --unlock is the longer report, with the derivation counters and the exposure flags.

Giving an agent a wallet

Section titled “Giving an agent a wallet”

The vault is custody Tier 1: it holds your keys and never shares them. An agent trades from a TEE wallet (custody Tier 2), which you promote out of the vault with candle vault promote, bound to one API key and pinned to a cold vault key where its funds go home. The walkthrough is Custody tiers: the vault and TEE wallets.

Eight words and 24 words are different things

Section titled “Eight words and 24 words are different things”

This trips up almost everyone, and the distinction is the whole model:

  • The eight words are your passphrase. They open the encrypted file sitting on this machine. Lose them and that file is scrap.
  • The 24 words are the vault. They are the seed every key is derived from. They rebuild your keys on any machine, forever, with or without that file.

So the file is convenience and the phrase is custody. If your laptop vanishes tonight, the 24 words on paper are what survive. If you only kept the eight words, you kept the lock and lost the keys.

FAQ

Section titled “FAQ”

What exactly are the 24 words? Is it a private key?

Section titled “What exactly are the 24 words? Is it a private key?”

No. It is a standard BIP-39 mnemonic encoding 32 bytes of root entropy: a seed, not a key. Individual keys are derived from it with SLIP-0010 ed25519 at paths like m/44'/501'/0'/0'. One seed produces many keys, deterministically, so the same 24 words reproduce the same addresses anywhere.

What encrypts the vault, and where does my passphrase live?

Section titled “What encrypts the vault, and where does my passphrase live?”

The vault file holds envelopes, each an independent way to unwrap the same key material under AES-256-GCM. The passphrase envelope stores Argon2id parameters, a salt, and the wrapped blob.

Your passphrase itself is stored nowhere: not in the file, not in your keychain, not on disk. Typing it re-derives the unwrapping key. That is also why no one, including us, can recover it for you.

Why does every command ask for the passphrase again?

Section titled “Why does every command ask for the passphrase again?”

There is no unlocked session, deliberately. Each command that needs your keys opens the vault, uses it, and wipes it, so there is no window where the decrypted root is sitting in memory waiting to be used by something else.

vault new-key does one extra thing: after writing, it re-opens the file it just wrote and re-derives the address from those bytes, so the guarantee is about what is on disk rather than what was in memory. That is the verified line in its output.

Can I use Touch ID or a passkey instead of typing a passphrase?

Section titled “Can I use Touch ID or a passkey instead of typing a passphrase?”

Not yet. Both are built and both are waiting on Apple’s approval of Candle’s signed macOS helper, and until that ships vault factor add touch-id and vault factor add passkey refuse with a typed error rather than doing something weaker.

When they land: Touch ID becomes a daily-use factor for that one Mac, since the key lives in that Mac’s Secure Enclave and cannot leave it, and re-enrolling a fingerprint invalidates it. A synced passkey is the portable one, since it follows your Apple account. Neither replaces the passphrase, which stays as the floor underneath them.

Can I use a hardware security key?

Section titled “Can I use a hardware security key?”

Yes, if the key supports the hmac-secret extension (FIDO2 with PRF). Add it with candle vault factor add security-key.

The key is another way to open the vault, not a second step on top of the passphrase. Any one factor opens it alone, so the passphrase still works without the key, and the key works without the passphrase.

Older keys without that extension are refused rather than downgraded: a YubiKey 4, for example, answers VAULT_PRF_UNSUPPORTED and nothing is written. The refusal happens on feature detection, before you are asked for a PIN, and no weaker derivation is substituted in its place.

Is my vault backed up to iCloud?

Section titled “Is my vault backed up to iCloud?”

No. Nothing is backed up automatically, anywhere. The vault lives at ~/.config/candle/vault.enc and nothing syncs it. Backups happen only when you run vault backup.

You may back up to iCloud Drive if you want, but the copy is sealed: it carries the passphrase and security-key envelopes only, and any Touch ID or passkey envelopes are stripped from it. The reason is that one Apple account should never hold both an encrypted vault and a factor that opens it. Other cloud folders are treated the same way, and so is any destination the CLI cannot confidently place, such as a network share or an unfamiliar sync client. --accept-shared-domain writes the full copy instead and records that you chose it.

Can I recover everything from just the 24 words?

Section titled “Can I recover everything from just the 24 words?”

Most things, with four limits worth knowing before you rely on it:

  • Derived keys, within bounds. vault restore --phrase reproduces indices inside explicit limits (--count for vault keys, --tee-count for TEE wallets). It does not scan forever, and a key that was allocated but never used can be missed.
  • Imported keys are not derived. Anything carried in from the older wallet store has its own random secret that no phrase can reproduce. Only a file backup saves those.
  • Labels and server-side state are not in the phrase. Names, linked wallets and delegations live in the file or on Candle’s side.
  • A restored vault is recovery-only. vault new-key, vault promote --from and external new refuse in it, permanently and by design: restoring reproduces what the old seed already determined, but it cannot safely claim a new index when the old boundary was never recorded. To allocate again, start a fresh vault and move funds across.

No vault at ..., but vault init says one already exists

Section titled “No vault at ..., but vault init says one already exists”

You are pointing two commands at two different files. --keystore applies to the one command you typed it on; leave it off and the CLI uses its default, ~/.config/candle/vault.enc. Both messages name the path they used, so compare those two paths first.

If you keep a vault somewhere other than the default, set the directory once instead of repeating the flag:

export CANDLE_CONFIG_DIR="$HOME/my-vault-dir"
candle vault status --unlock

Every command then reads $CANDLE_CONFIG_DIR/vault.enc. Note that the CLI does not expand ~ for you: your shell does, so an unexpanded ~something/vault.enc becomes a directory literally named ~something.

brew install fails with “invalid syntax in tap”

Section titled “brew install fails with “invalid syntax in tap””

Your Homebrew is too old to read the formula. Update it, clear any half-tapped state, and retry:

brew update
brew untap candledottv/tap 2>/dev/null; brew tap candledottv/tap
brew install candledottv/tap/candle

The install script above works regardless of Homebrew’s version.

candle update ran but printed nothing

Section titled “candle update ran but printed nothing”

Versions before 0.8.4 updated silently, and the version doing the updating is the old one, so the first update off an old build shows nothing. From 0.8.4 onward it names the version it is moving to and reports each step as it downloads and verifies.

Where do my credentials live?

Section titled “Where do my credentials live?”

Your device token and API key go in your OS keychain, not in a file. Non-secret configuration sits in ~/.config/candle, which CANDLE_CONFIG_DIR relocates. candle auth status and candle doctor both name the backend in use.

Next steps

Section titled “Next steps”