EngramEngramDocs

CLI Reference

The engram CLI provides a local interface for setup, ingesting text, querying the store, and checking subnet status.

Install

bash
pip install engram-subnet
engram --help
Tip
The CLI defaults to a local FAISS store and sentence-transformers embedder. No OpenAI key or running miner needed for basic use.

engram init

Interactive setup wizard — creates a .env file and verifies your installation. The fastest way to get started.

bash
engram init

The wizard asks about your role and writes the right config:

bash
$ engram init
╭──────────────────────────────────────────╮
│  Welcome to Engram                        │
│  This wizard will help you set up your   │
│  environment.                             │
╰──────────────────────────────────────────╯
What are you setting up?
  [miner]     Run a miner node and earn TAO
  [validator] Run a validator and set weights
  [dev]       Use the SDK locally
> miner
Subtensor network [finney/test/ws://...]: test
Subnet UID: 450
Wallet name: default
Hotkey name: miner
Your public IP address: 1.2.3.4
...
✓ Written: /your/project/.env
Checking your installation...
  ✓  engram package          installed
  ✓  engram-core (Rust)      built
  ✓  openai                  installed
  ✓  bittensor               installed
Next steps:
  btcli subnet register --netuid 450 ...
  python neurons/miner.py
FlagDescription
--role miner|validator|devSkip the role prompt
--out PATHOutput path for .env file (default .env)
--forceOverwrite existing .env without prompting

engram ingest

bash
# Ingest a string
engram ingest "The transformer architecture changed everything."
# With metadata
engram ingest "BERT uses bidirectional representations." --meta '{"source":"arxiv"}'
# From a JSONL file
engram ingest --file data/corpus.jsonl
# Ingest an entire directory recursively (.txt, .md, .jsonl)
engram ingest --dir ./docs
# Custom source label
engram ingest "My note" --source personal-notes
FlagDescription
TEXTText to embed and store (positional)
--file, -f PATHPath to a .txt or .jsonl file
--dir PATHRecursively ingest all .txt / .md / .jsonl files
--meta, -m JSONJSON metadata string (default {})
--source, -s STRSource label added to metadata (default "cli")

engram query

bash
engram query "how does self-attention work?"
engram query "neural network training" --top-k 10
engram query "vector databases" --meta
FlagDescription
TEXTSearch query (required)
--top-k, -k INTNumber of results to return (default 5)
--metaShow metadata column in results table

engram status

bash
# Local store status
engram status
# Live metagraph — connects to chain and probes all miners
engram status --live
engram status --live --netuid 450
FlagDescription
--live, -lFetch live data from chain and health-check all miners
--netuid INTSubnet UID (overrides NETUID env var)

engram wallet-stats

bash
# All wallet activity on this miner
engram wallet-stats
# Single wallet detail
engram wallet-stats 5FHGPfixdXLs...
# With live TAO stake
engram wallet-stats --live --netuid 450

Environment variables

VariableDefaultDescription
FAISS_INDEX_PATH./data/engram.indexLocal FAISS index file path
USE_LOCAL_EMBEDDERtrueUse sentence-transformers (no API key needed)
OPENAI_API_KEY—Required if USE_LOCAL_EMBEDDER=false
SUBTENSOR_NETWORK—Network for --live (test, finney, ws://...)
NETUID450Default subnet UID
WALLET_NAMEdefaultWallet coldkey name
WALLET_HOTKEYdefaultWallet hotkey name
MINER_URLhttp://127.0.0.1:8091Miner URL for wallet-stats command
Previous
Exceptions
Next
Run a Miner
engram docs · v0.1edit on github →