Command line

The app comes with a command line, zikaron: one subcommand per operation, each printing one JSON value on standard output, with the outcome in its exit code. It works in three ways: through the desktop app, with a credential, or on its own.

Putting it in the terminal

Turn on “Enable the zikaron command” under “Terminal” in Settings › Command line and AI control, and zikaron works in any terminal. Installed from the .pkg or .deb, it already does; with the AppImage, install the .deb for the command line. On Windows, zikaron.exe runs in a terminal.

“Automation level” on the same page decides how the command line writes the desktop’s sealed data: “Through the desktop app” (on by default) is way one, and “With a credential” (off by default) is way two. While “With a credential” is on, “Through the desktop app” is greyed out, so one road is open at any time; with both off, the sealed data is written by the desktop alone. On its own, the command line writes a ledger folder of its own, whatever these two switches say.

The “Terminal” group on the same page also has “Connect an AI app”: press “Copy config” and paste the config into an AI Agent’s MCP settings, and the AI Agent can call the command line without a terminal (zikaron mcp). Each write goes way one or way two as the switches on this page say; see Connecting through MCP.

Run zikaron contract for every subcommand, its flags and the exit codes. How to write each command is in Developer guide · Command line.

Way one: through the desktop app

While the desktop is open and unlocked, a command carrying your data folder, --home "<data folder>", is handed to the running ZIKARON Desk. The desktop signs as you and writes to its ledger, along the same path as your own clicks: the same checks, the same messages, the window updating at once. The private keys and the passcode stay in the desktop the whole time; the command line only hands over requests.

• Where the data folder is: under “Details” in Settings › Local data, the “Data folder” row gives the path of this role’s data folder for the current identity.
• Read-only work: checking other people’s material and other read-only work the command line does directly.
• Work on the desktop: setting the passcode, managing keys, whole-machine backups, turning on “With a credential”, “Resend with higher fees” and anything that asks for the passcode are done on the desktop. Handing a ledger over to another key is done by hand on the desktop too: succeed with --home always answers E_ON_DESKTOP.
• When the channel is open: the local channel is open to you on this computer alone, and only while “Through the desktop app” is on and the desktop is unlocked and holding this data folder; locking, closing the data folder or quitting shuts it, and the command line gets exit code 4. While “With a credential” is on, a command with --home answers E_DESKTOP with detail ALONE: drop --home and write it as in way two.

Way two: with a credential

On the desktop you grant a credential for a set time, and with it the command line writes the desktop’s sealed ledger and sends its queue directly, with the desktop closed or locked.

1. Turn it on. Under “Automation level” in Settings › Command line and AI control, turn on “With a credential”. On the card that opens, enter the passcode and fill in how long it lasts: three cells for days, hours and minutes (at most 365, 23 and 59, from one minute up to a year in all), or turn on “Does not expire”; press “Turn on”. While it is on, the row below says when the credential expires.
2. Find the ledger folder. Under “Details” in Settings › Local data, the “Data folder” row gives the data folder’s path; --ledger in a command takes the ledger folder inside it.
3. Write and read. A command that writes an entry carries --ledger "<the ledger folder in the data folder>" and signs with this identity’s key for this role from the desktop’s key store, with no --key, --key-file or --home; what it writes goes into the queue the way the desktop’s own entries do. Reading commands, such as checking and exporting a record kit, take the same folder, and an export carries the chosen records’ originals the way the desktop does.
4. Put on chain. zikaron anchor --ledger "<the ledger folder in the data folder>" sends this data folder’s queue: the chain, the registry contract and the nodes come from this data folder’s settings, and the proxy from “Proxy” in Settings › Network.

Taking it back. Turning off “With a credential” deletes the credential. On expiry it is deleted, the desktop says so, and the command line answers E_CREDENTIAL_EXPIRED. After the main identity changes or the machine is restored from a backup, the credential lapses and the switch goes back off, with the message “The master key was replaced; “With a credential” is off.” It keeps working after a passcode change, and a wrong credential counts toward no passcode attempts.

Taking turns with the desktop. The desktop and the command line each take this data folder’s writer lock for each write and let it go once done. When the command line meets the desktop writing, it answers E_HOME_HELD: try again shortly. When the desktop meets the command line writing, that write is left undone and the message “The command line is writing.” appears, its “Go to settings” leading to that page. While open and unlocked, the desktop looks at the disk once a second, so entries the command line writes show up at once; with “Auto put on chain” on, the send card opens as it does after an entry of the desktop’s own.

The credential file. It sits in the machine folder, readable and writable by your system account alone, and seals the master key that opens this computer’s data. Whoever or whatever holds it can, as the command line does, write ledgers and send transactions to put entries on chain as each identity on this computer, until it expires or you turn the switch off. Set the time to what you need, and turn it off when done.

Two modes for putting on chain

Ways one and two put entries on chain as “Putting on chain from the command line” under “Anchoring” in Settings › Command line and AI control says:

Send automatically

The default. Everything sendable in the queue goes as one transaction, the way “Put all on chain” does, paying the fee from this identity’s address. Once in a block, the command line hands back the block number and transaction hash; if the time runs out first, it answers that the transaction is still outside a block (exit code 4), and the batch stays in flight for the desktop or the next anchoring to ask after its receipt. Through the desktop it waits 30 seconds; with a credential, 90 seconds by default. When some records in the batch are already on chain, nothing is sent and the answer is E_ON_CHAIN; once those leave the queue, sending again sends the rest.

Queue only

The entries stay in the queue, and the command line answers “Queued; waiting for the user to send it from the desktop” (E_QUEUED, exit code 3). Through the desktop, the desktop shows the toast “N records from the command line are queued” and alerts you once. You check them on the desktop and press “Confirm and send”.

The card that turns on “With a credential” says so plainly: while putting on chain from the command line sends automatically, the command line can spend this identity’s gas.

Way three: the command line on its own

The command line can start from nothing by itself, with no desktop and no graphical interface:

1. Make a key. In your own terminal, run zikaron keygen, which prints a new address and its private key. Save the private key alone in a file, set so only you can read it (chmod 600 on macOS and Linux), and point later commands at it with --key-file.
2. Add gas. Send a little ETH to that address.
3. Create a ledger. zikaron init --ledger "<ledger folder>" --key-file "<key file>" --statement "<description>". Later writes, such as records, grants, revocations and notes, carry those two and go into this ledger folder.
4. Put on chain. anchor takes the key file with --key-file, the node with --endpoint, --form registry for the registry route, the registry contract with --registry (on Ethereum mainnet, 0x36Ea8A857a5FE813429d4D9947000C644A88809A) and the entry IDs to anchor with --hash, which can repeat, so one transaction anchors several. Before signing, it asks the registry contract whether this key has already anchored those IDs: if one is on chain, it answers E_ON_CHAIN, with names listing the ones already there, and sends nothing. Running the same command again first asks after the transactions it already signed, so one anchoring is paid for once.
5. Check and present. scan and audit check the ledger against the chain; kit-export exports a record kit (by default one file at the --out path, named as you choose, the desktop’s exports ending in .zkit; a folder with --as folder); kit-verify checks a record kit item by item, judging what is on chain once given a scan reading; check-grant verifies a grant; add --to-key <public key> (or --to <address> with --endpoint) to kit-export to encrypt the kit to one recipient, and --originals-to <folder> to kit-verify to take the originals out to that folder.

The ledger it writes is the same format the desktop writes, and anyone can verify it with the desktop app or the command line. To bring this ledger into the desktop later, import the private key with “Import key”, then use “Adopt existing ledger folder” under “Advanced options” in Settings › Local data. Once adopted, the desktop goes on writing this ledger: the command line writing the old folder again answers E_ADOPTED, and the old folder stays as it was; to go on writing from the command line, use way two. For a ledger written by turns in two places, see Handing a ledger over.

Handing a ledger over

A ledger can pass back and forth between two places, such as a command-line ledger folder on a remote machine and the desktop’s data folder on your own computer; one place writes at any time. Both ends use the same pair of commands:

• zikaron hand-over --ledger "<this place>" --out "<handoff file>" writes the whole ledger as one handoff file (.zkhand), and this place stops writing at once; a write there answers E_HANDED_OFF. If the file is lost on the way, running it again writes the same one.
• zikaron take-over --ledger "<that place>" --handoff "<handoff file>" takes a handoff file that follows on from this place, writes in the entries this place lacks in sequence order, and this place writes again. When it cannot take the file, it answers E_HANDOFF, with token naming why, and writes nothing.

Both places write the same ledger with the same key: on the command-line side, the private key given with --key-file; on the desktop side, an identity made by importing that same private key with “Import key”. The desktop side takes the ledger folder in the data folder and needs “With a credential” on, with the desktop locked or not. After the desktop side hands the ledger over, a write to it on the desktop shows “This ledger was handed off to another place.”: once that place hands it back, take the handoff file with the command line, then write. Records of what went on chain stay out of the handoff file: the desktop’s next ledger check reads the chain afresh and queues only what the chain lacks, so what the other place anchored costs no second gas.

Plain files

With the command line on its own, these sit on disk as plain files:

The key file is what matters. Anyone or any program that can read files as this system account can read it, so keep it this way:

• Small funds, a ledger of its own. Use this key for this purpose alone, with only enough ETH at its address for gas, apart from your main identity.
• Guard the system account. Turn on the system’s full-disk encryption; allow remote logins by key alone.
• Hand the key to the command line by file alone. Give it with --key-file; the command line takes a key file only you can read. Keep the file outside synced folders and automatic backup folders, with one more copy somewhere safe and offline.
• Prefer the desktop. In ways one and two, the key stays in the desktop’s key store, encrypted under the passcode. Keep the command line on its own for when a machine with no screen and a single dedicated key are truly needed.

Which way to use

What the command line answers