uno CLI command reference

This page lists every uno command, grouped by task, and gives the full flag tables for uno kit pay, uno kit quota and uno kit resume. It is for developers and AI agents who need to find a command or check a flag. The page is self-contained.

Some values on this page can change. They are marked "today". Run uno kit capabilities for the live limits and prices. Run uno <command> --help or uno <command> --schema for the exact flags of any command. See Agent mode and exit codes for the JSON envelope and the exit-code table.

Find a command

Do not guess flags. Ask the CLI.

uno --llms --format json
uno --llms-full --format json
uno kit pay --schema

uno --llms-full --format json prints every command with its flags and output fields. The commands on this page match the command tree that the CLI tests expect, plus uno skills add. The hidden kit ops group is left out.

Global flags

These flags work on every command. See Agent mode and exit codes for what each does.

Group	Flags
Account and origin	`--account`, `--expect-account`, `--anonymous`, `--api`, `--kit-api`, `--confirm-kit-api-origin`, `--kit-target`
Diagnostics	`--telemetry`, `--trace`
Output	`--format`, `--json`, `--filter-output`, `--full-output`, `--token-count`, `--token-limit`, `--token-offset`
Discovery	`--help`, `--llms`, `--llms-full`, `--schema`

No command takes a credential as a flag.

Commands by task

Each line is one command. Descriptions are short forms of the CLI help.

Command	What it does
`uno login`	Sign in to Uno. Local macOS uses a native passkey. SSH and other platforms use web login.
`uno logout`	Sign out one account, or every saved account with `--all`.
`uno whoami`	Show the signed-in account and Uno username.
`uno auth status`	Show local session and passkey support without network requests.
`uno account create`	Create an unverified account and sign in. The key stays on this machine. Losing the key loses the account.
`uno account verify`	Hand an unverified account to uno.fun to add an email and a passkey.
`uno account login`	Sign in to an unverified account with the key on this machine.
`uno account list`	List saved accounts for this origin without network requests.
`uno account current`	Validate and show the selected account online.
`uno account switch`	Change the active local account. Explicit pins keep their own account.
`uno account bind`	Bind a physical folder tree to an account in your config.
`uno account unbind`	Remove this folder's binding and reveal any parent binding.
`uno account key export`	Write a copy of the account key to a new file. Anyone with the file controls the account.
`uno account key import`	Restore an account key from a file that `uno account key export` wrote.

Username and profile

Command	What it does
`uno username`	Show your Uno username.
`uno username check`	Check whether a Uno username is available, and why not.
`uno username set`	Set or change your Uno username. The server may refuse a change during a cooldown.
`uno profile update`	Set your given name, family name and bio.

Read Kits

Command	What it does
`uno kit discover`	List recently updated public Kits, newest first.
`uno kit list`	List an owner's Kits. With no owner, list your own, private ones included.
`uno kit profile`	Read the public profile linked to a Kit owner.
`uno kit show`	List all committed files.
`uno kit cat`	Print a committed file as text, or in `data.text` with JSON output.
`uno kit get`	Download a Kit object to a new file.
`uno kit log`	Read commit history with pagination.
`uno kit diff`	Compare files between two revisions.
`uno kit refs`	List the Kit's branches and tags.
`uno kit read-ref`	Read the current commit ID of a branch or tag, to pass to a write as `--expected-head`.
`uno kit object-url`	Find an accessible object URL. Use `kit get` for private downloads.
`uno kit layout`	Inspect a file's content chunks and proof metadata.
`uno kit prove`	Read content proof metadata for a revision or file.
`uno kit verify`	Check signature validity, authorization at acceptance and later revocation separately.
`uno kit clone`	Clone a Kit into a new folder with its history, for reading.
`uno kit pull`	Fetch a Kit clone and fast-forward its branch. It never merges.

Write Kits

Kit writes need --operation when you run in agent mode. See Agent mode and exit codes.

Command	What it does
`uno kit upload`	Upload a local file or folder into an upload session, then finalize it. With `--commit`, commit in the same run.
`uno kit upload-session`	Open an upload session for staging. It sends no bytes.
`uno kit stage`	Stage one local file up to `staging.inline_call_bytes`. Use `kit upload` for larger files.
`uno kit stage-url`	Stage a public HTTPS URL. It polls for up to 10 minutes.
`uno kit commit`	Commit an upload session. The first commit creates the Kit. A new Kit is public by default. `--draft` keeps it private until `kit visibility`.
`uno kit job`	Read the state of a commit job. `--wait` polls until it ends.
`uno kit publish-video`	Upload a video through the video-minute flow, wait for its job, then commit a `kit.json` that names the job.
`uno kit tag`	Create a tag on a revision of your Kit. A tag is immutable and cannot be deleted.
`uno kit ref-update`	Move a branch of your Kit to a commit, only if its head is still `--expected-old`.
`uno kit ref-delete`	Delete a branch of your Kit.
`uno kit revert`	Commit the inverse of one commit onto a branch, only if its head is still `--expected-head`.
`uno kit remix`	Copy a Kit into a new Kit of your own. The new Kit keeps the source history.
`uno kit visibility`	Set your repo to public or private.
`uno kit delete`	Delete a repo you own. Its refs go at once. Its object bytes are retained for 30 days.
`uno kit resume`	Replay a saved write by its operation id. See kit resume.

Pay and check storage

Command	What it does
`uno kit capabilities`	List server limits and storage pricing. Read-only.
`uno kit quota`	Show storage state, usage and limits. See kit quota.
`uno kit purchase`	Look up a recorded owner purchase without paying or creating a quote.
`uno kit pay`	Buy storage with Tempo or Stripe Link, or quote an Agent plan. See kit pay.

Signing keys

Command	What it does
`uno kit whoami`	Show your Uno username and Kit owner identity.
`uno kit key list`	Read this owner's current keys and server custody state.
`uno kit key enroll`	Create or import a signing key and enroll it.
`uno kit key mode`	Print or choose local or custodial signing for this profile.
`uno kit key custody`	Turn server custodial signing on or off.
`uno kit key rotate`	Replace the custodial signing key.
`uno kit key revoke`	Revoke a signing key from now or a past time.
`uno kit key remove`	Retire a self-owned key. Its history stays valid.

Command	What it does
`uno star`	Star Kits, and list stars.
`uno star add`	Star a public Kit.
`uno star remove`	Remove your star from a Kit.
`uno star list`	List your stars, the Kits a user starred, or a Kit's star count and stargazers.
`uno follow`	Follow Uno users, and list follows.
`uno follow add`	Follow a Uno user.
`uno follow remove`	Stop following a Uno user.
`uno follow list`	List who you or a user follow, or their followers with `--followers`.
`uno activity`	Read the public activity feed, newest first.
`uno notifications list`	List your inbox, newest first.
`uno notifications mark-read`	Mark notifications through a sequence number read.

Install and diagnose

Command	What it does
`uno doctor`	Check the install: files, PATH, wrapper and auto-update. It reads local state only.
`uno update`	Update uno to the newest release, check for one, or return to the previous version.
`uno telemetry status`	Show consent and pending reports without network requests.
`uno skills add`	Write the uno agent skill to `<dir>/uno/SKILL.md`. The default folder is `~/.agents/skills`. See Install the CLI.

kit pay

uno kit pay buys Kit storage. It has three modes.

Block purchase. --blocks with --renew or --no-renew. This is the App account path.
Subscription. --subscribe starts automatic Tempo payments. --cancel-subscription stops them.
Agent capacity. --capacity with --months quotes an Agent plan and prints a Tempo wallet command. This mode never pays.

kit pay is a guarded command. When an agent marker is set (UNO_AGENT=1, CLAUDECODE or CODEX_THREAD_ID), or when stdin or stdout is not a terminal, it exits 2 unless you pass --yes or --dry-run. --json on a terminal does not count. The guard applies to every mode, so the Agent capacity quote needs --yes too. Get your user's approval for the exact terms first. A printed command that adds --yes is not approval.

Flags

Flag	Type	Meaning
`--operation <id>`	string	Saved operation id. Reuse it with identical arguments after an interruption. Required in agent mode.
`--blocks <n>`	integer, 1 to 4294967295	Paid blocks. Default 1. `uno kit capabilities` lists the block limit (`payment.blocks`) and the price per block.
`--renew`	boolean	Start or renew a term.
`--no-renew`	boolean	Add blocks to an active term.
`--subscribe`	boolean	Start Tempo payments that renew every 30 days. Today: USD 9.99 for 50 GB of paid storage.
`--subscription-plan <id>`	string	App subscription plan id. Needs `--subscribe`.
`--cancel-subscription <id>`	GUID	Stop future Tempo payments for this subscription id.
`--method tempo\|stripe`	enum	Payment method. `stripe` opens Stripe Link in an interactive terminal.
`--capacity <size>`	string	Agent plan: total storage, such as `500MB` or `1GB`. Needs `--months`.
`--months <n>`	integer, 0 or more	Agent plan: whole 30-day months to add. `0` only raises the capacity of an active plan.
`--payment-file <path>`	path	A `0600` file that holds one serialized MPP `Payment` credential from an external wallet.
`--yes`	boolean	Skip the prompt. Required when stdin or stdout is not a terminal.
`--dry-run`	boolean	Print the change without writing. Identity and price reads may run.

--capacity takes MB, GB or TB in decimal units. Today the accepted range is 100MB to 10TB in exact 100MB steps. --capacity is the total, including stored history, not the amount to add.

Combination rules

--capacity and --months go together. One without the other exits 2.
--capacity and --months do not combine with --blocks, --renew, --subscribe, --method, --payment-file, --cancel-subscription or --subscription-plan.
A one-time block purchase needs --renew or --no-renew. Without one, the command exits 2 before it sends anything.
Write --renew and --no-renew without a value. --renew=false exits 2 with the reason INVALID_RENEW. Passing both exits 2.
--subscribe and --cancel-subscription exclude each other.
--subscribe and --cancel-subscription do not combine with --blocks, --renew or --method stripe.
--cancel-subscription does not combine with --payment-file.
--subscription-plan needs --subscribe.
--method stripe does not combine with --payment-file.
A saved operation keeps its original flags. Passing --operation with a different --renew choice does not change the saved request.
A fresh block purchase is checked against payment.blocks before it is journaled. A request over the limit exits 9.

Stripe Link runs only in an interactive terminal with no explicit format flag. In every other case, --method stripe exits 15 and prints the command for you to run in a terminal.

Outcomes

Exit	Meaning	Next step
0	Settled. For Agent capacity, `state` is `settled` and `results` lists the classification, applied amount, capacity, dates and transaction.	Retry the write that needed storage.
15	An unpaid quote or challenge. `error.details.payment` holds the terms.	Get approval, then pay.
14	A payment may be in flight.	Wait. Run `uno kit purchase <purchase_id>`. Never pay again to recover.
21	Purchases are off, or the quote does not match your request, account or owner.	Stop. Do not pay the quote.
24	The backend has no capacity purchases yet.	Stop.
9	The purchase failed, expired or belongs to an old network.	Read it with `uno kit purchase`. Start a new operation to buy again.

Exit 15: error.details.payment

Exit 15 carries the payment terms as data in error.details.payment. The object holds no challenge text and no secret.

Blocks

A write that hits the payment gate, and uno kit pay --blocks, both exit 15 with this object.

Field	Meaning
`amount`	The amount the server named, as a string. `null` if empty.
`token`	The token address. When the challenge names no address, the currency name.
`chain`	The chain id as a number. `null` if the challenge names none.
`blocks`	The number of paid blocks. `1` when the challenge does not name a count.
`pay_command`	The command to run next.

kit pay --blocks adds these fields to the Tempo path.

Field	Meaning
`challenge_file`	Path of the saved challenge file.
`request_file`	Path of the request body file for the Tempo handoff, or `null`.
`offers`	Present when you did not pass `--method` and Stripe Link is offered. A list of one Tempo entry and one Stripe entry.

With --method stripe, the object holds the Stripe terms and offers holds one Stripe entry.

Each offers entry has method, intent, amount, currency and pay_command. The Stripe entry also has test_mode.

For the Tempo path, pay_command is a tempo request command that pays and settles in one step. When the CLI cannot prepare that command, pay_command is uno kit pay --blocks <n> <--renew|--no-renew> --payment-file <file> --operation <id>. A write-gate error prints uno kit pay --blocks <n> <flag> --operation <id>, which saves the challenge.

Agent capacity

uno kit pay --capacity <size> --months <n> exits 15 with a frozen server quote. The error details also hold purchase_id, state set to payment_required, next_command and, when you passed one, operation.

Field	Meaning
`purchase_id`	The owner purchase id.
`quote_id`	The quote id.
`amount`	The exact amount to pay, as a decimal string.
`token`	The token address.
`chain`	The chain id as a number.
`capacity_bytes`	The quoted total capacity in bytes.
`months`	The number of months the quote adds.
`usd_per_gb_month`	The quoted price, as a decimal string. Today `0.50`.
`expires_at`	When the quote ends, in Unix seconds.
`no_refund`	The no-refund statement from the server.
`pay_url`	The backend's exact payment link for this purchase.
`pay_command`	A `tempo request` command that pays `pay_url`.

pay_command pins the selected account with an x-uno-expect-account header. Run it as printed. The CLI accepts pay_url only for this owner, this purchase and an HTTPS origin, and only when the quote matches your request. Another payer needs only the pay_url. The link grants payment, not ownership.

Today a quote ends 30 minutes after creation, or sooner at the plan's next expiry or restore cutoff. There is no cash refund. A late, stale or duplicate payment becomes storage time.

Examples

Preview an Agent quote. This sends nothing.

uno kit pay --capacity 1GB --months 1 --dry-run --format json

Request the quote. This never pays. --yes only lets the quote request run past the guard.

uno kit pay --capacity 1GB --months 1 --yes --operation buy-1 --format json

Preview a block purchase.

uno kit pay --blocks 1 --renew --dry-run --format json

Rerun the same command after a lost reply. The saved operation reuses the server idempotency key. Never start a new operation while a payment may be in flight.

For the full payment flow, see Pay with Tempo, Pay with Stripe Link and Recover an uncertain payment.

kit quota

uno kit quota shows storage state, usage and limits. It is a read. With --format json, it also returns recovery guidance and paginated Kit sizes.

uno kit quota --format json

Flags

Flag	Type	Meaning
`--kit-limit <n>`	integer, 1 to 100	Kits per storage page. Default 10.
`--kit-cursor <cursor>`	string	Continue Kit sizes with `storage.kit_sizes.next_cursor`.
`--purchase-limit <n>`	integer, 1 to 100	Purchases per storage page. Default 10.
`--purchase-cursor <cursor>`	string	Continue purchases with `storage.next_purchase_cursor`.

To page through all Kits, repeat the command with --kit-cursor set to the last next_cursor until it is empty. Do the same for purchases with --purchase-cursor.

Storage fields

The storage observation is under storage in JSON output. It is present on servers that run the Agent storage implementation.

Field	Meaning
`billing_class`	The account's billing class: App or Agent.
`plan`	The Agent plan: `state`, `capacity_bytes`, `starts_at`, `expires_at`, `grace_ends_at`, `restore_cutoff_at`.
`used_bytes`	Bytes stored, including history.
`reserved_bytes`	Bytes reserved by writes that have not settled.
`available_bytes`	Unreserved active capacity. Zero without an active plan.
`minimum_fit_bytes`	The smallest capacity that fits `used + reserved + the refused write`, rounded up to 100 MB. At least 100 MB. Retained deleted bytes are excluded.
`kit_sizes`	A page. `kit_sizes.kits[]` has one entry per Kit incarnation with `repository_id`, `name`, `used_bytes`, `reserved_bytes`, `retained_deleted_bytes` and `deleted`. `kit_sizes.next_cursor` continues.
`retained_deleted_bytes`	Bytes of deleted content still retained.
`retained_capacity_basis_bytes`	The capacity basis for the retained-byte limit. It persists after the plan expires.
`retained_threshold_bytes`	The retained-byte limit. Absent when enforcement is not active. Absent does not mean zero.
`earliest_reclaim_at`	The earliest time retained bytes can be reclaimed, in Unix seconds.
`operation_limits`	The upload limits: `hosted_upload_bytes`, `hosted_upload_files`, `remix_source_bytes`, `inline_commit_bytes`. Buying capacity does not raise them.
`promo_grant`	The original promo grant: `capacity_bytes`, `expires_at`, `source`.
`pricing`	Agent pricing: capacity bounds and step, `usd_per_gb_month`, `offers_enabled`, `network_epoch`, `chain_id`, `asset`, `asset_decimals`.
`purchases`	Recorded owner purchases, open and paid.
`next_purchase_cursor`	Continues `purchases`.
`open_purchase_id`	The purchase that holds the owner's pending lease, when any.

Today these limits apply to the plan lifecycle. Writes stop at expiry. Grace lasts 30 days. Suspension lasts until the restore cutoff, 60 days after expiry. Deleted bytes stay counted until reclaimed, and writes are refused when they exceed three times the capacity basis. Check uno kit capabilities before you rely on these numbers.

The JSON also keeps older App fields such as quota_bytes, used_bytes and paid_until. A write_ops_cap or write_bytes_cap of 0 means the server reports no write-rate window. The write_* fields then do not limit your writes.

kit resume

uno kit resume <operation> replays the exact saved mutation from the local journal. It does not read local file bytes.

uno kit resume <operation> --format json

Arguments

Argument	Type	Meaning
`operation`	string, required	The saved operation id to replay.

kit resume takes no other flags of its own. Add the global flags. In agent mode, a recovery command carries --account, --expect-account, --api and --kit-api. Keep all four and the original operation.

What it can replay

kit resume can replay a saved write of these kinds: visibility change, upload session start, staged files, staged URL, commit, ref update, ref delete, tag, revert, remix, repo delete and pay. It also replays a frozen signed write.

It sends the same request with the same idempotency key. A saved answer is returned without a new call. A journal of any other procedure exits 2 with "The journal does not name a supported kit mutation."

What it cannot replay

Uploads. kit resume refuses every upload journal: <operation>, <operation>.stage and <operation>.finalize. It cannot stage or finalize, because it never reads local files. It prints the uno kit upload command to run instead. Run that command again with the same files, flags and operation.
Unfinished file stages. A kit stage journal holds a digest and a size for each file, never the content. Run uno kit stage again with the same file and the same --operation. kit resume names that command.
Video publishing stages. Run uno kit publish-video again with the original operation.

Rules

A journal is local to UNO_CONFIG_DIR. An operation id is not a server recovery token.
A journal records the account, the API origin, the Kit origin and the Kit owner. kit resume for another recorded account exits 25 with the reason operation_account_mismatch. It sends nothing. Do not switch accounts to force a replay.
Do not edit journals.
After a payment that may have landed, check with uno kit quota or uno kit purchase <purchase_id> before you pay again.

uno CLI command reference

Find a command

Global flags

Commands by task

Sign in and manage accounts

Username and profile

Read Kits

Write Kits

Pay and check storage

Signing keys

Social, activity and notifications

Install and diagnose

kit pay

Flags

Combination rules

Outcomes

Exit 15: error.details.payment

Blocks

Agent capacity

Examples

kit quota

Flags

Storage fields

kit resume

Arguments

What it can replay

What it cannot replay

Rules

Related pages