Bineric Code/CLI Documentation

Bincode CLI Documentation

Command-line interface for interacting with the Bineric platform. Work with AI directly in your terminal.

Introduction

Bincode CLI is a command-line tool for interacting with the Bineric platform. When you run any command, if you're not logged in, the CLI automatically opens the login page in your browser.

Installation

Install Bincode CLI globally using npm, bun, or pnpm:

bash
npm install -g bincode

Or via Bun: bun install -g bincode or pnpm: pnpm install -g bincode

Authentication

When you run any command, if you're not logged in, the CLI automatically opens the login page in your browser. Token is stored in bincode.json or bincode.jsonc.

bash
bincode login # Manual login
bincode logout # Logout

TUI

Using the Bincode terminal user interface.

Bincode provides an interactive terminal interface or TUI for working on your projects with an LLM.

Running Bincode starts the TUI for the current directory.

bash
bincode

Or you can start it for a specific working directory.

bash
bincode /path/to/project

Once you're in the TUI, you can prompt it with a message.

bash
Give me a quick summary of the codebase.

File reference

You can reference files in your messages using @. This does a fuzzy file search in the current working directory.

Tip: You can also use @ to reference files in your messages.

bash
How is auth handled in @packages/functions/src/api/index.ts?

The content of the file is added to the conversation automatically.

Commands

When using the Bincode TUI, you can type / followed by a command name to quickly execute actions. For example:

bash
/help

agents

Opens the agents panel where you can view, select, and switch between different agents (build, plan, docs).

bash
/agents

compact

Compact the current session.

bash
/compact

exit

Exit Bincode. Aliases: /quit, /q

bash
/exit

help

Show the help dialog.

bash
/help

init

Create or update AGENTS.md file.

bash
/init

models

List available models.

bash
/models

Keybind: ctrl+x m

new

Start a new conversation. Alias: /clear

bash
/new

Keybind: ctrl+x n

sessions

List and switch between sessions.

bash
/sessions

CLI

Command-based usage for Bincode in your terminal.

Login

bash
bincode login

This command will automatically open the login page in your browser. Same login is used for BinCode and the chatbot at /login.

Logout

bash
bincode logout

Logs out from the current session and clears stored authentication tokens

Run

Run a chat with the AI. Provide your message and optionally specify a model or other options.

Command Syntax

bash
bincode run <message>

Examples

1. Basic usage (uses default model):

bash
bincode run "Explain closures in JavaScript"

2. Run with a specific model:

bash
bincode run "hello" --model Bineric/gpt-5

3. Run with file attachment:

bash
bincode run "Refactor this code" --file src/index.ts

4. Run with multiple files:

bash
bincode run "Review these files" --file src/index.ts --file src/utils.ts

5. Run with model and file together:

bash
bincode run "Optimize this code" --model Bineric/gpt-5 --file src/index.ts

Available Options

  • --model, -m <provider/model> - Specify the model to use (e.g., Bineric/gpt-5)
  • --file, -f <file-path> - Attach one or more files (can be used multiple times)

Web

Launch Bincode in a web UI. This command starts a local web server that provides a browser-based interface to interact with Bincode.

bash
bincode web

Models

List and explore available AI models. You can view all models, filter by provider, or get detailed information about specific models.

Command Syntax

bash
bincode models [provider]

Examples

1. List all available models:

bash
bincode models Bineric

2. Refresh the model cache:

bash
bincode models --refresh

Agent

Manage and create agents. Bincode comes with built-in agents for different workflows, and you can create your own custom agents.

Built-in Agents

build (default)

The default agent. Executes tools based on configured permissions — use this for writing, editing, and building code.

plan

Read-only analysis agent. Disallows all edit tools — ideal for reviewing code and planning changes before implementation.

general

General-purpose agent for researching complex questions and executing multi-step tasks in parallel.

explore

Fast agent specialized for exploring codebases — finding files by patterns, searching code for keywords, or answering questions about the codebase.

System Agents

Bincode also includes system agents that run automatically in the background. You don't need to invoke them directly.

compaction

Automatically compresses long conversations when the context window is getting full. Summarizes what was done, what's in progress, and key decisions — so the conversation can continue without losing important context.

List Agents

View all available agents including built-in and custom agents.

bash
bincode agent list

Create a Custom Agent

Create your own agent with a specific description, tools, and mode.

bash
bincode agent create

Options

  • --description <string> - What the agent should do
  • --mode <string> - Agent mode: all, primary, or subagent
  • --tools <string> - Comma-separated list of tools to enable (e.g., bash, read, write, edit, glob, grep)
  • --model, -m <provider/model> - Model to use (e.g., Bineric/gpt-5)
  • --path <string> - Directory path to generate the agent file

Examples

1. Create an agent interactively:

bash
bincode agent create

2. Create an agent with all options:

bash
bincode agent create --description "Review code for security issues" --mode subagent --tools read,glob,grep

Session

Manage your conversation sessions. List recent sessions or delete old ones.

List Sessions

bash
bincode session list

Options

  • --max-count, -n <number> - Limit to N most recent sessions
  • --format <string> - Output format: table (default) or json

Delete a Session

bash
bincode session delete <sessionID>

Examples

1. List 10 most recent sessions:

bash
bincode session list -n 10

2. List sessions as JSON:

bash
bincode session list --format json

3. Delete a session:

bash
bincode session delete abc123

Stats

View token usage and cost statistics across your sessions.

Command Syntax

bash
bincode stats [OPTIONS]

Options

  • --days <number> - Show stats for the last N days (default: all time)
  • --tools <number> - Number of tools to show (default: all)
  • --models [number] - Show model statistics, optionally limit to top N models
  • --project <string> - Filter by project (use empty string '' for current project)

What it shows

  • Overview — Total sessions, messages, and active days
  • Cost & Tokens — Total cost, average cost per day, tokens per session, input/output/cache breakdown
  • Model Usage — Per-model message counts, tokens, and cost (when enabled with --models)
  • Tool Usage — Tools used with frequency counts and percentages

Examples

1. View all-time stats:

bash
bincode stats

2. Last 30 days with top 5 models:

bash
bincode stats --days 30 --models 5

3. Stats for current project only:

bash
bincode stats --project ''

Export

Export a session's conversation data as JSON. Useful for backups, sharing, or analysis.

Command Syntax

bash
bincode export [sessionID]

If no session ID is provided, you'll be prompted to select from your recent sessions.

Examples

1. Export a specific session:

bash
bincode export abc123

2. Export interactively (select from list):

bash
bincode export

3. Export and save to a file:

bash
bincode export abc123 > session-backup.json

Serve

Start a headless Bincode server. This allows external tools and IDEs to connect to Bincode over HTTP.

Command Syntax

bash
bincode serve [OPTIONS]

Options

  • --port <number> - Port to listen on (default: auto-select)
  • --hostname <string> - Hostname to listen on (default: 127.0.0.1)
  • --mdns - Enable mDNS service discovery
  • --cors <string> - Additional domains to allow for CORS (can be specified multiple times)

Examples

1. Start with auto-selected port:

bash
bincode serve

2. Start on a specific port:

bash
bincode serve --port 8080

3. Start with mDNS discovery enabled:

bash
bincode serve --port 8080 --mdns

Upgrade

Upgrade Bincode to the latest or a specific version.

Command Syntax

bash
bincode upgrade [version]

Options

  • --method, -m <string> - Installation method: npm, bun, pnpm, brew, or curl

Examples

1. Upgrade to the latest version:

bash
bincode upgrade

2. Upgrade to a specific version:

bash
bincode upgrade 0.1.48

3. Upgrade using a specific package manager:

bash
bincode upgrade --method bun

Uninstall

Uninstall Bincode CLI from your system.

bash
npm uninstall -g bincode