Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nonhumans.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Nonhumans CLI is the fastest way to go from zero to a running agent. Use it to scaffold new projects, push deployments, tail logs, inspect your agent’s inbox and wallet, and manage secrets — all without leaving your terminal. It pairs with both the TypeScript and Python SDKs and works equally well in local development and CI pipelines.

​
Installation

# Use without installing — always runs the latest version
npx nonhumans

# Or install globally for a persistent command
npm install -g @nonhumans/cli
Running via npx nonhumans guarantees you are always on the latest CLI version with no manual upgrade step. Use the global install when you want tab completion or a fixed version in CI.

​
Authentication

Before running any command, authenticate the CLI with your Nonhumans account: 
npx nonhumans login
This opens your browser to complete OAuth. Once you approve, the CLI stores a local token at ~/.nonhumans/credentials and all subsequent commands use it automatically.
In headless environments (CI, Docker), pass your API key via the --api-key flag or the NONHUMANS_KEY environment variable instead of running login.

​
Command reference

​
nonhumans init [name]

Scaffold a new agent project in the current directory (or a named subdirectory). Creates a project structure with a starter agent file, a nonhumans.json config, and an example .env. 
npx nonhumans init my-agent

​
nonhumans deploy

Build and push your agent to always-on compute. The CLI reads your nonhumans.json for the entry point and runtime, then streams build output to your terminal. 
npx nonhumans deploy

​
nonhumans status

Check the current runtime status of your deployed agent — whether it is running, sleeping, or in an error state. 
npx nonhumans status

​
nonhumans logs

Tail live log output from your running agent. Press Ctrl+C to stop streaming. 
npx nonhumans logs
npx nonhumans logs --since 1h   # show logs from the last hour

​
nonhumans email

Inspect your agent’s email inbox from the terminal. Lists recent messages with sender, subject, and timestamp. 
npx nonhumans email              # list inbox
npx nonhumans email read <id>    # print a single message body

​
nonhumans wallet

Check balances and send payments without opening a dashboard. 
npx nonhumans wallet balance              # show all balances
npx nonhumans wallet send \
  --to 0xAbC123... \
  --amount 50 \
  --currency usdc \
  --memo "Payout March"

​
nonhumans memory

Search and inspect everything stored in your agent’s vector memory. 
npx nonhumans memory search "email preferences"
npx nonhumans memory list --limit 20

​
nonhumans vault set/get

Store and retrieve secrets without touching the dashboard. 
npx nonhumans vault set stripe_key sk_live_...
npx nonhumans vault get stripe_key
npx nonhumans vault list            # show all key names (values hidden)
npx nonhumans vault delete stripe_key

​
nonhumans agents list

List every agent associated with your account, along with their handle, status, and creation date. 
npx nonhumans agents list

​
Global flags

Every command accepts these flags:
FlagDescription
--api-key <key>Override the stored credential with a specific API key.
--output jsonPrint output as JSON — ideal for scripting and piping into jq.
--helpPrint usage information for any command.
Combine --output json with jq to build powerful shell pipelines:
npx nonhumans wallet balance --output json | jq '.usdc'

​
From init to deploy — step by step

The following walkthrough takes you from a blank directory to a live, always-on agent in under five minutes.
1

Authenticate

Log in to your Nonhumans account. The CLI stores your token locally.
npx nonhumans login
2

Scaffold your project

Create a new agent project. Replace my-agent with your desired handle.
npx nonhumans init my-agent
cd my-agent
The scaffolded directory looks like this:
my-agent/
├── agent.ts          # entry point
├── nonhumans.json    # project config
├── package.json
└── .env.example
3

Set your API key

Copy .env.example to .env and paste your API key.
cp .env.example .env
# Edit .env and set NONHUMANS_KEY=your_key_here
4

Write your agent logic

Open agent.ts and build your agent using the SDK. The scaffold includes a minimal example to get you started.
import { Nonhumans } from '@nonhumans/sdk'

const agent = new Nonhumans({ apiKey: process.env.NONHUMANS_KEY })

export default async function run() {
  const emails = await agent.email.list({ unread: true })
  console.log(`Inbox has ${emails.length} unread message(s).`)
}
5

Deploy to always-on compute

Push your agent. The CLI bundles your code, uploads it, and starts the runtime.
npx nonhumans deploy
You will see streaming build output. A successful deploy prints your agent’s public URL:
✓ Build complete
✓ Agent live at https://my-agent.nonhumans.ai
6

Verify it is running

Confirm the deployment and watch live logs.
npx nonhumans status
npx nonhumans logs

​
Next steps

TypeScript SDK

Explore all SDK modules — email, wallet, memory, compute, and more.

Python SDK

Build agents in Python with sync and async support.