XnY CLI 101

Install the xny command, connect it to XnY Cloud, and upload and anchor a contribution.

xny is the command-line client for XnY Cloud. Use it from a workstation, a CI job, or an agent when you need a scriptable way to authenticate an app and anchor contributed data. The CLI sends requests to XnY Cloud; it does not call the executor or storage services directly.

The current CLI covers three jobs:

keep connection settings in named profiles;
authenticate with an app API key;
upload a payload and anchor its contribution metadata.

Before you start

An XnY platform administrator must create your app and issue its API key. The administrator must also bind every contributor DID that the app will anchor. You need:

the XnY Cloud base URL for your environment;
an API key for the app;
a contributor DID that is bound to the app;
an existing task that can accept the contribution.

The CLI does not create apps, issue keys, bind DIDs, or create protocol tasks.

Install

Homebrew

Homebrew installs the checksummed release archive for your operating system and CPU. It does not compile the CLI, so Go is not required.

brew install humanbased-ai/tap/xny
xny version

Upgrade or remove it with the usual Homebrew commands:

brew upgrade humanbased-ai/tap/xny
brew uninstall xny

The tap supports Apple Silicon and Intel Macs. The GitHub Release also provides Linux archives for AMD64 and ARM64.

Download a release archive

Download the archive for your platform from the public xny releases, verify it against checksums.txt, extract it, and move xny to a directory on your PATH.

archive=xny_0.1.1_darwin_arm64.tar.gz
grep "  ${archive}$" checksums.txt | shasum -a 256 -c -
tar -xzf "$archive"
install -m 0755 xny /usr/local/bin/xny
xny version

Choose the filename for your release and platform. On Linux, use sha256sum -c - in place of shasum -a 256 -c -. The selected archive must report OK.

Connect to XnY Cloud

Create a named profile for the environment and make it active:

xny profile add staging --url https://cloud.staging.xny.ai
xny profile use staging

A profile contains only its name and base URL. The API key is stored separately in the operating system keychain.

xny auth login

The prompt does not echo the key. Verify both the credential and the connection:

xny auth status

A successful response identifies the app:

authenticated as app 2230571013400000000 using profile staging

Useful profile commands:

xny profile list
xny --profile production auth status
xny profile remove old-environment

--profile selects a profile for one command without changing the active profile. Removing a profile also deletes its saved keychain credential.

Prepare a contribution

Anchoring needs two local inputs:

a JSON object with contribution metadata;
the raw payload file to preserve and reference from that metadata.

Create contribution.json:

{
  "submission_id": "submission-123",
  "task_id": "2026092009452200100074",
  "contributor_did_id": "233553709574595699934924049546270335941",
  "publisher": "did:xny:publisher",
  "published_at": "2026-09-29T08:00:00Z",
  "tags": { "source": "partner-import" },
  "kind": "SAMPLE",
  "verdict": 1,
  "grade": 85
}

Use identifiers issued for your own app and protocol task. Metadata is limited to 64 KiB. The payload can be any file up to 32 MiB; the CLI infers its media type from the filename and otherwise uses application/octet-stream.

Upload and anchor

xny anchor push \
  --metadata contribution.json \
  --payload sample.parquet

XnY Cloud uploads the payload to managed object storage, calculates its integrity hash, builds external contribution metadata, and submits the anchor job. The CLI waits for the operation to reach a terminal state. A successful text response includes the job ID, status, and idempotency key:

job_id=3f71c694-a637-418d-96bf-f53a65669343 status=finalized idempotency_key=anchor:...

Ask for JSON when another program consumes the result:

xny anchor push \
  --metadata contribution.json \
  --payload sample.parquet \
  --output json

Submit now and poll later

For a long-running job, return as soon as Cloud accepts it:

xny anchor push \
  --metadata contribution.json \
  --payload sample.parquet \
  --no-wait \
  --output json
 
xny anchor status <job_id> --output json

The operation is complete when its status is finalized, failed, or cancelled. A finalized operation includes its transaction hash and on-chain entity ID.

Retry an uncertain submission safely

Every submission has an idempotency key. Save the key printed by the first attempt. If the connection fails before you receive a result, repeat the request with the same key:

xny anchor push \
  --metadata contribution.json \
  --payload sample.parquet \
  --idempotency-key 'anchor:<key-from-first-attempt>'

Do not invent a new key for the retry: a new key represents a new submission.

Use the CLI in CI

Containers and CI runners can use environment variables instead of profile and keychain storage:

export XNY_API_URL=https://cloud.staging.xny.ai
export XNY_API_KEY='...'
 
xny auth status --output json
xny anchor push \
  --metadata contribution.json \
  --payload sample.parquet \
  --output json

Load XNY_API_KEY from the CI platform's secret store. Do not pass it as a command-line flag, commit it to a repository, or print it in job logs.

XNY_PROFILE selects a saved profile when one is available. An explicit --profile flag takes precedence over XNY_PROFILE, and XNY_API_URL plus XNY_API_KEY take precedence over saved credentials.

Common options

Option	Purpose
`--output text`	Human-readable output; this is the default.
`--output json`	Stable machine-readable output for scripts and agents.
`--profile <name>`	Use one saved profile for this command.
`--content-type <type>`	Override the payload media type.
`--wait-timeout <duration>`	Bound upload and polling time; default `15m`.
`--poll-interval <duration>`	Change the status polling interval; default `2s`.

Run xny --help or xny <command> --help for the complete command-level reference.

Troubleshooting

no active profile or profile ... not found

Create a profile with xny profile add, then select it with xny profile use.

Authentication fails

Run xny auth login again, then xny auth status. Confirm that the profile URL and API key belong to the same environment.

Cloud rejects the contributor DID

Ask the platform administrator to bind that DID to your app. Authentication of the app and authorization of a contributor DID are separate checks.

The task is rejected or not finalized

The task_id must name an existing task that is eligible for contributions. Use xny anchor status <job_id> --output json to retain the complete operation and error details when reporting the problem.

A command times out while the server may still be working

The timeout stops local waiting; it does not prove the remote operation stopped. Query the returned job ID, or retry with the same idempotency key if no job ID was returned.

On this page