CLI reference

The curta binary

curta is the bin of the @curta/cli package, for Node 20 and later. It is built on @curta/sdk and carries the same WebAssembly build of curta-core, so it converts, quotes and plans turns with the code the program runs.

How arguments are read

• The first word after curta is the command.
• A word that starts with -- is a flag, and the next word is its value. Flags go anywhere after the command.
• --once is the one flag that takes no value.
• Every other word is a positional argument, in the order written.

A flag written without its value ends the command with Missing value for --<flag>. A required argument left out ends it with Missing <argument> followed by the usage text.

Connection and wallet

Every command but convert and help reaches the chain and signs with a wallet. Each of these is a flag or an environment variable, and the flag is used when both are set.

--rpcURLenv CURTA_RPC_URL, default http://127.0.0.1:8314

The RPC endpoint. The default is a validator on the same machine. Reads and confirmations use the confirmed commitment.

--keypairpathenv CURTA_KEYPAIR, required

The keypair file of the wallet that signs and pays: a JSON array of the secret key’s bytes.

--program-idaddressenv CURTA_PROGRAM_ID, default De7awjrzJXdgcozSjQshCJej2xzfDasPRBzTrw7PegFn

The address of the curta program.

export CURTA_RPC_URL=<rpc endpoint>
export CURTA_KEYPAIR=<path of the keypair file>

curta seal <model>
curta seal <model> --rpc <another endpoint> --keypair <another file>

The CLI reads these three settings and no other configuration.

curta convert

curta convert <checkpoint> --tokenizer <file> --out <artifact>

Turns a llama2.c checkpoint into Curta’s integer weight format and writes the artifact. It works on files alone: no RPC endpoint and no keypair.

<checkpoint>pathrequired

The llama2.c checkpoint file.

--tokenizerpathrequired

The checkpoint’s tokenizer file, in the llama2.c binary format.

--outpathrequired

Where the artifact is written.

Prints one JSON object:

artifactstring

The --out path.

bytesnumber

The artifact’s size.

hashstring

The weights hash, 64 hexadecimal digits.

configobject

dim, hiddenDim, layers, heads, kvHeads, vocabSize, contextLength.

sectionsnumber[]

The length of each section in bytes, in order.

turnsstring

The count of turns an 8-token run on the prompt “Once upon a time” takes at temperature zero.

A checkpoint or tokenizer that does not match its format ends the command with Checkpoint conversion failed. The weight format describes both input files and the artifact.

curta publish

curta publish <artifact> [--name <name>] [--royalty <lamports>] [--state <file>]

Creates the Model account, its vault and one weight account per section, then writes the weights in 800-byte chunks, one transaction per chunk, 24 in flight at a time. The signing wallet becomes the model’s publisher and pays the rent of every account.

<artifact>pathrequired

The file curta convert wrote.

--namestringdefault: the artifact’s file name without its last extension

The model’s name, 1 to 64 bytes of UTF-8.

--royaltyinteger, lamportsdefault 0

The royalty per token.

--statepathdefault keys/<artifact file name>.upload.json

The upload’s state file, relative to the working directory. Its folder is created when missing.

The state file holds the keypairs of the model account and the weight accounts and the artifact’s weights hash. When it exists, the command continues that upload: it reads each weight account’s bitmap and sends only the chunks still to write.

Progress goes to stderr, one line for each percent:

Uploaded <written>/<total> bytes (<percent>%)

At the end the command prints one JSON object:

modelstring

The model’s address.

statestring

The state file’s path.

weightBytesnumber

The artifact’s size.

rentLamportsstring

The rent this invocation paid for the accounts it created.

transactionsnumber

The transactions this invocation sent: account creations and chunk writes.

elapsedMsnumber

How long it took, in milliseconds.

Errors particular to this command:

Publish a model walks through the whole job.

curta seal

curta seal <model>

Sends seal_model transactions until the model is sealed. Each one hashes the next 65,536 bytes of the written weights, and the last compares the result with the weights hash. The signing wallet is the model’s publisher.

<model>addressrequired

The model’s address.

Prints one JSON object: model, the address, and transactions, the count this invocation sent. On a sealed model that count is 0.

curta set-royalty

curta set-royalty <model> <lamports>

Sets the model’s royalty per token. The signing wallet is the model’s publisher.

<model>addressrequired

The model’s address.

<lamports>integerrequired

The royalty per generated token, in lamports.

Prints the transaction’s signature.

curta claim

curta claim <model> [lamports]

Moves royalties from the model’s vault to the signing wallet, the model’s publisher.

<model>addressrequired

The model’s address.

[lamports]integerdefault 0

The amount to claim. Left out or 0, the command claims the vault’s whole balance above its rent.

Prints the transaction’s signature.

curta run

curta run <model> <prompt> [--max-tokens 32] [--temperature 0] [--seed 1]

Opens a run on a sealed model, lands every turn itself with the same wallet, and prints the result when the run is complete. The wallet deposits the quoted budget and the run account’s rent, and receives the turn reward of each turn it lands.

<model>addressrequired

The address of a sealed model.

<prompt>textrequired

The text the model continues, up to 1,024 bytes of UTF-8. Every positional word after the model is part of the prompt, joined by single spaces, so quote a prompt to keep its spacing.

--max-tokensintegerdefault 32

The most tokens to generate, from 1 to the model’s context length.

--temperaturenumberdefault 0

From 0 to 16. Zero takes the most likely token every time.

--seedintegerdefault 1

The 64-bit seed of the sampler.

The run’s address goes to stderr as soon as the run is open:

Run <address>

When the run is complete the command prints one JSON object:

addressstring

The run’s address.

textstring

The model’s output, read from the run account.

tokensnumber[]

The ids of the tokens the model produced.

turnsstring

The count of turns the run took.

curta run <model> "Once upon a time" --max-tokens 8 --temperature 0 --seed 1

The command ends with Model is not sealed for a model that is still uploading, and with Run is starved or Run is cancelled when the run leaves the running state before it completes. Runs and turns describes the states.

curta crank

curta crank [--once]

Turns every running run and settles every run that has ended. The signing wallet lands the turns and receives their turn rewards.

--onceflag

Makes one pass over the runs and exits. Without it the command keeps watching until it receives SIGINT or SIGTERM.

A pass takes the program’s runs in the order they were opened, oldest first. A running run gets one turn. A complete or cancelled run that is not settled gets its settle. The list of runs is read again whenever the program’s transaction history changes, and an idle pass waits half a second before the next.

Each transaction that lands prints one JSON object:

kind"turn" | "settle"

What the transaction was.

runstring

The run’s address.

signaturestring

The transaction’s signature.

turnsLandednumber

Turns this invocation has landed so far.

lamportsEarnedstring

Turn rewards this invocation has earned so far, in lamports.

With --once the command ends by printing the totals, one JSON object with turnsLanded and lamportsEarned. Run a cranker covers running it as a service.

curta help

curta help

curta help, or curta alone, prints the usage text:

curta convert <checkpoint> --tokenizer <file> --out <artifact>
curta publish <artifact> [--name <name>] [--royalty <lamports>] [--state <file>]
curta seal <model>
curta set-royalty <model> <lamports>
curta claim <model> [lamports]
curta crank [--once]
curta run <model> <prompt> [--max-tokens 32] [--temperature 0] [--seed 1]

Chain commands accept --rpc, --keypair, --program-id or CURTA_RPC_URL, CURTA_KEYPAIR, CURTA_PROGRAM_ID.

Output, errors and exit codes

• Results go to stdout. JSON is indented by two spaces, and every amount or count the SDK holds as a bigint is written as a decimal string.
• Progress goes to stderr: the upload lines of publish and the Run line of run.
• A command that succeeds exits with code 0. A command that fails writes one message to stderr and exits with code 1.

How transactions are sent

Every transaction the CLI sends is built the same way:

• The wallet in --keypair is the fee payer and signs. New accounts sign beside it when a transaction creates them.
• The transaction asks for a compute unit limit of 1,400,000, the most a transaction may use.
• It is simulated before it is sent, so a transaction the program would reject ends the command before it reaches the chain.
• The CLI waits until the transaction is confirmed. While it waits it sends the same signed transaction again every two seconds, until the transaction lands or its blockhash expires.

The curta-core binary

curta-core is the native build of the inference core, a second binary for work on artifact files with no chain involved. It is built from the crate with the std feature:

# from backend/
cargo build --manifest-path crates/curta-core/Cargo.toml --features std --release

Its arguments are positional, in the order shown. A command that fails writes its message to stderr and exits with code 1.

curta-core convert

curta-core convert <checkpoint> <tokenizer> <output>

Converts a llama2.c checkpoint and its tokenizer file and writes the artifact to <output>. Prints Converted <bytes> bytes to <output>, then the artifact’s directory as inspect prints it.

curta-core inspect

curta-core inspect <artifact>

Prints the artifact’s configuration and section count, then one line per section with its offset in the file and its length:

config=Config { dim: 64, hidden_dim: 172, layers: 5, heads: 8, kv_heads: 4, vocab_size: 512, seq_len: 512 } sections=2
section 0: offset=0 bytes=68440
section 1: offset=68440 bytes=288704

curta-core run, replay and verify

curta-core run <artifact> [prompt] [max-tokens] [temperature] [seed]
curta-core replay <artifact> [prompt] [max-tokens] [temperature] [seed]
curta-core verify <artifact> [prompt] [max-tokens]

All three compute a run from the artifact, turn by turn, with the planner the program uses.

<artifact>pathrequired

An artifact file.

[prompt]textdefault Once upon a time

The prompt, one argument.

[max-tokens]integerdefault 32

The most tokens to generate.

[temperature]integerdefault 0

The temperature with 16 fractional bits: the temperature times 65,536. A temperature of 1 is 65536.

[seed]integerdefault 42

The 64-bit seed of the sampler.

Replay and determinism shows replay and verify in use.