Nonhumans CLI: Scaffold, Deploy, and Manage Agents

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:

Flag	Description
`--api-key <key>`	Override the stored credential with a specific API key.
`--output json`	Print output as JSON — ideal for scripting and piping into `jq`.
`--help`	Print 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.

Authenticate

npx nonhumans login

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

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

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).`)
}

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

Verify it is running

Confirm the deployment and watch live logs.

npx nonhumans status
npx nonhumans logs

Nonhumans CLI: Scaffold, Deploy, and Manage Agents

Installation

Authentication

Command reference

`nonhumans init [name]`

`nonhumans deploy`

`nonhumans status`

`nonhumans logs`

`nonhumans email`

`nonhumans wallet`

`nonhumans memory`

`nonhumans vault set/get`

`nonhumans agents list`

Global flags

From `init` to `deploy` — step by step

Next steps

TypeScript SDK

Python SDK

​Installation

​Authentication

​Command reference

​nonhumans init [name]

​nonhumans deploy

​nonhumans status

​nonhumans logs

​nonhumans email

​nonhumans wallet

​nonhumans memory

​nonhumans vault set/get

​nonhumans agents list

​Global flags

​From init to deploy — step by step

​Next steps

TypeScript SDK

Python SDK

Installation

Authentication

Command reference

`nonhumans init [name]`

`nonhumans deploy`

`nonhumans status`

`nonhumans logs`

`nonhumans email`

`nonhumans wallet`

`nonhumans memory`

`nonhumans vault set/get`

`nonhumans agents list`

Global flags

From `init` to `deploy` — step by step

Next steps