---
sidebar_position: 3
title: '@zibby/cli'
---

# @zibby/cli

[![npm](https://img.shields.io/npm/v/@zibby/cli.svg)](https://www.npmjs.com/package/@zibby/cli)

The user-facing entry point — the `zibby` command. Install once globally; it pulls in `@zibby/core`, `@zibby/agent-workflow`, `@zibby/skills` automatically.

```bash
npm install -g @zibby/cli
zibby --version
```

## What it does

- **Scaffolds** agents: `zibby agent new <name>`
- **Runs** agents locally (one-shot): `zibby agent run <name>`
- **Deploys** to Zibby Cloud (Heroku-style bundles): `zibby agent deploy <name>`
- **Triggers** deployed agents: `zibby agent trigger <uuid>`
- **Tails** logs: `zibby agent logs <uuid> -t`
- **Manages** auth: `zibby login`, `zibby logout`, `zibby status`

The full command catalog lives at [CLI Reference](../cli-reference).

## Self-contained agent projects

`zibby agent new` creates an agent as a **self-contained npm project** — its own `package.json`, its own `node_modules`. So an agent can pull in arbitrary deps (PDF libraries, custom MCP servers, your own SDK) without polluting the parent project.

```
my-app/
├── package.json
├── src/
└── .zibby/
    └── workflows/
        └── my-agent/
            ├── package.json     # agent's own deps
            ├── node_modules/
            ├── graph.mjs
            └── nodes/
```

The cloud bundle build does the same — `npm install` runs *inside* the agent folder, scoped to its own package.json.

## Configuration

The CLI reads `.zibby.config.mjs` at the project root for defaults:

```js
// .zibby.config.mjs
export default {
  paths: {
    workflows: '.zibby/workflows',   // override if you want a different folder
    output: '.zibby/output',
  },
  agent: {
    default: 'cursor',                // fallback agent when no per-node override
  },
  models: {
    default: 'auto',
    execute_live: 'claude-opus-4.6', // per-node model override
  },
};
```

`zibby agent deploy` resolves this file locally and ships the result as `zibby.config.json` inside the deploy bundle, so the cloud runtime sees the same `agent` block, per-node `models`, and other declarative knobs as your local runs. Function values are dropped at deploy time (config is data, not code) — if you need runtime variation in cloud, use [per-agent env vars](../cloud/env-vars).

## Source

- npm: [`@zibby/cli`](https://www.npmjs.com/package/@zibby/cli)
- See [CLI Reference](../cli-reference) for every command + option