Skip to content
0xkey-ioPublic

About

0xkey platform CLI (API keys, stamped requests, wallets)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

0xkey CLI

Command-line tool for the 0xkey platform: generate API keys, stamp Public API requests, manage wallets and private keys, import/export enclave material, and sign payloads / Ethereum transactions.

Shares ~/.config/0xkey/ with AgentOS 0xkey-wallet (same disk contract for keys and config).

Install

From source

git clone https://github.com/0xkey-io/cli
cd cli
make install   # installs to ~/.local/bin/0xkey

go install

go install github.com/0xkey-io/cli/cmd/0xkey@latest

GitHub Releases

Annotated tags vX.Y.Z publish multi-arch binaries (darwin / linux, x86_64 / aarch64) plus SHA256SUMS on the Releases page.

Quickstart

export ZEROXKEY_ORGANIZATION_ID="<your-org-uuid>"

# 1) Generate a local API key (stores under ~/.config/0xkey/keys/)
0xkey generate api-key --organization "$ZEROXKEY_ORGANIZATION_ID" --key-name quickstart

# 2) Register the printed publicKey in the Dashboard (My Profile → API keys)

# 3) Persist non-secret defaults
0xkey config set zeroxkey.organization "$ZEROXKEY_ORGANIZATION_ID"
0xkey config set zeroxkey.key_name quickstart

0xkey whoami
0xkey wallets create --name default
0xkey wallets accounts create --wallet default --address-format ADDRESS_FORMAT_ETHEREUM
0xkey activities list

Configuration

~/.config/0xkey/
├── config.toml          # host / organization / key_name only (no secrets)
├── keys/                # API key material (private files mode 0600)
└── encryption-keys/     # TEK for import / export
Source Prefix / path
Flags --host, --organization, --key-name, …
Env ZEROXKEY_* (never 0XKEY_* — POSIX forbids digit-leading names)
Config ~/.config/0xkey/config.toml

Precedence (high → low): flags → env → config.toml → built-in defaults.

Secrets never go in config.toml. Private keys stay in the keystore and are referenced by --key-name / --encryption-key-name.

Global flags

Flag Env Purpose
--host ZEROXKEY_API_BASE_URL API hostname (default api.0xkey.io)
--organization ZEROXKEY_ORGANIZATION_ID Organization UUID
-k / --key-name ZEROXKEY_API_KEY_NAME API key name in keystore
-d / --keys-folder ZEROXKEY_KEYS_FOLDER API keystore directory
--encryption-key-name — TEK name for import/export
--encryption-keys-folder — TEK keystore directory
-o / --output — json (default) or yaml

Capabilities

What you can do today, grouped by job. Commands that only list enums are under Reference data.

Capability Commands Notes
Auth & identity generate api-key, whoami, config * Register pubkey in Dashboard after generate api-key
Stamp Public API calls request Stamp and POST arbitrary /public/v1/* bodies
Wallets wallets create|list|export|init-import|import HD wallets
Wallet accounts wallets accounts create|list|export Derive addresses (ETH, Solana, …)
Standalone private keys private-keys create|list|export|init-import|import Non-HD keys
Import / export crypto generate encryption-key, encrypt, decrypt HPKE bundles around enclave material
Sign raw payload raw sign Arbitrary payload + encoding + hash
Sign Ethereum tx ethereum transaction Returns signedTransaction hex
Activities activities list|get Inspect submit history / status
Sub-organizations organizations create Create a sub-organization under the current org
Policies policies create|list|deploy-defaults Direct Public API creates skip auto-policies; use deploy-defaults with the sub-org root key
Shell UX completion, version, help Autocomplete + build info

Command reference

0xkey
├── version                         Build / version info
├── completion                      Shell autocompletion (bash|zsh|fish|powershell)
├── config
│   ├── list                        Effective config (never prints secrets)
│   ├── get <key>                   One value (zeroxkey.host|organization|key_name)
│   └── set <key> <value>           Persist a non-secret default
├── generate
│   ├── api-key                     Local API keypair → ~/.config/0xkey/keys/
│   └── encryption-key              TEK for import/export (--user required)
├── whoami                          Authenticated user + org for current API key
├── request                         Stamp (+ optionally POST) an arbitrary API body
├── wallets
│   ├── create                      Create HD wallet
│   ├── list                        List wallets
│   ├── export                      Export wallet mnemonic bundle
│   ├── init-import                 Start wallet import (enclave import bundle)
│   ├── import                      Finish wallet import (encrypted bundle)
│   └── accounts
│       ├── create                  Derive account (address-format / curve / path)
│       ├── list                    List accounts for a wallet
│       └── export                  Export one account’s key material
├── policies                        (alias: policy)
│   ├── create                      Create one policy (V3)
│   ├── list                        List policies
│   └── deploy-defaults             Deploy 5 default sub-org policies (CLI / direct API path)
├── private-keys                    (alias: pk)
│   ├── create                      Create standalone private key
│   ├── list                        List private keys
│   ├── export                      Export private key bundle
│   ├── init-import                 Start private-key import
│   └── import                      Finish private-key import
├── encrypt                         Plaintext → encrypted import bundle
├── decrypt                         Export bundle → plaintext
├── raw
│   └── sign                        SignRawPayloadV2
├── ethereum                        (alias: eth)
│   └── transaction                 SignTransactionV2 (alias: tx)
├── activities
│   ├── list                        List org activities [--status …]
│   └── get <activity-id>           Activity detail
├── organizations                   (aliases: o, org, organization)
│   └── create                      Create sub-organization
├── curves list                     Supported curves
├── address-formats list            Supported address formats
└── transaction-types list          Supported transaction types

Every command accepts --help for flags. Prefer that over duplicating every flag here.

Reference data

Command Returns
0xkey curves list Curve enum values for create/import
0xkey address-formats list Address format enums (e.g. ADDRESS_FORMAT_ETHEREUM)
0xkey transaction-types list Transaction type enums for signing

Common workflows

Stamp a raw Public API request

Paths use 0xkey Public API style: /public/v1/query/* and /public/v1/submit/*.

0xkey request \
  --path /public/v1/query/whoami \
  --body "{\"organizationId\":\"$ZEROXKEY_ORGANIZATION_ID\"}"

Preview stamp + curl without posting:

0xkey request --no-post \
  --path /public/v1/query/whoami \
  --body "{\"organizationId\":\"$ZEROXKEY_ORGANIZATION_ID\"}"

--body may be - (stdin) or @file.json.

Sign a raw payload

0xkey raw sign \
  -s 0xYourAddressOrPrivateKeyId \
  --payload "hello" \
  --payload-encoding PAYLOAD_ENCODING_TEXT_UTF8 \
  --hash-function HASH_FUNCTION_SHA256

Sign an Ethereum transaction

--payload is the unsigned transaction hex. Response includes signedTransaction.

0xkey ethereum transaction \
  -s 0xYourAddressOrPrivateKeyId \
  --payload <unsigned-tx-hex>

Export a wallet → decrypt locally

0xkey generate encryption-key --user "<user-uuid>" --encryption-key-name my-tek
0xkey wallets export \
  --name default \
  --encryption-key-name my-tek \
  --export-bundle-output /tmp/wallet.export.json
0xkey decrypt \
  --encryption-key-name my-tek \
  --export-bundle-input /tmp/wallet.export.json

Local / staging enclaves may need --signer-quorum-key <uncompressed-pubkey-hex> on encrypt / decrypt. Production should leave it unset (sdk-go production quorum key).

Import a mnemonic wallet

init-import → encrypt (mnemonic) → import
0xkey wallets init-import --user "<user-uuid>" --import-bundle-output /tmp/import.bundle.json
0xkey encrypt \
  --user "<user-uuid>" \
  --import-bundle-input /tmp/import.bundle.json \
  --plaintext-input /tmp/mnemonic.txt \
  --key-format mnemonic \
  --encrypted-bundle-output /tmp/encrypted.bundle.json
0xkey wallets import \
  --user "<user-uuid>" \
  --name imported \
  --encrypted-bundle-input /tmp/encrypted.bundle.json

Private-key import follows the same three steps under private-keys.

Create a sub-organization

0xkey organizations create \
  --name "team-a" \
  --root-api-public-key "<p256-pubkey-hex>"

Development

Builds against the published github.com/0xkey-io/sdk-go release; no sibling checkout or local replace is required.

make test
make build-local
./scripts/smoke.sh

Design notes (super-repo): docs/technical-design/H1_cli_developer_tool.md.

License

Apache License 2.0

About

0xkey platform CLI (API keys, stamped requests, wallets)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

⌂ 换网址