How do I install Factory’s CLI and run my first task with `droid`?

Factory’s CLI is the fastest way to get Droids running directly in your terminal or IDE. You install a single binary, authenticate once, and you can immediately delegate real engineering tasks—refactors, investigations, migrations—without changing your editor or workflow.

This guide walks through:

• Installing the Factory CLI on macOS, Linux, and Windows
• Authenticating and verifying your environment
• Running your first droid task end-to-end
• Basic patterns to integrate droid into your day-to-day development

---

Prerequisites

Before you install Factory’s CLI and run droid:

• Access to Factory
  • You’ll need a Factory account (org invite or signup from your team’s link).
• Terminal access
  • macOS or Linux shell (bash/zsh/fish)
  • Windows: PowerShell or WSL (Windows Subsystem for Linux) recommended
• Git and a codebase
  • Any Git repo you’re comfortable modifying (a sandbox repo is ideal for your first run).

Factory is model-agnostic and interface-agnostic; the CLI is just one surface. Once you’re set up here, the same Droids will be available in your IDE, browser, Slack/Teams, and CI/CD.

---

Step 1: Install Factory’s CLI

The CLI install is a single curl pipe with no extra setup. It’s designed to be repeatable in local machines, containers, and CI.

macOS and Linux

From your terminal:

curl -fsSL https://app.factory.ai/cli | sh

What this does:

• Downloads the latest factory CLI binary
• Places it on your PATH (typically ~/.factory/bin)
• Verifies basic integrity and prints a short summary

If you prefer being explicit about where the binary is placed, you can inspect the script first:

curl -fsSL https://app.factory.ai/cli -o factory-install.sh
less factory-install.sh
sh factory-install.sh

Windows

On Windows you have two practical paths:

Option A: PowerShell

Open PowerShell as your user (or in Windows Terminal) and run:

curl.exe -fsSL https://app.factory.ai/cli | sh

This uses the same installer under a POSIX-like shim. If you hit issues with sh on Windows, use WSL.

Option B: WSL (Recommended)

If you use WSL (Ubuntu/Debian/…):

1. Open your WSL terminal.

2. Run the same install command as Linux:

   curl -fsSL https://app.factory.ai/cli | sh
   

This keeps the experience consistent with macOS/Linux and works well for cross-platform teams.

---

Step 2: Verify the CLI Install

After the installer completes, verify the binary is available:

factory --version

You should see something like:

factory version X.Y.Z

If you get command not found:

1. Check where factory was installed:

   ls ~/.factory/bin
   

2. Ensure it’s on your PATH:

   echo 'export PATH="$HOME/.factory/bin:$PATH"' >> ~/.bashrc
   # or ~/.zshrc, then:
   source ~/.bashrc
   

3. Re-run:

   factory --version
   

Once factory resolves cleanly, you’re ready to authenticate and run droid.

---

Step 3: Authenticate the CLI

Authentication links your local CLI to your Factory account with the same strict permissions enforcement you have in the web app. Droids will only see what you can already access.

Launch the login flow

From any directory:

factory login

This will:

• Open a browser window to Factory’s auth page (or print a URL you can copy)
• Let you authenticate via your SSO (SAML/SSO) or email/password, depending on your org
• Bind a short-lived token to your CLI environment

Once complete, you should see a confirmation:

Successfully authenticated as you@company.com

To confirm:

factory whoami

This will show your user and organization context. All droid runs from this machine will use this identity, respecting your org’s policies, audit logging, and access controls.

---

Step 4: Understand the droid Command

The CLI exposes multiple capabilities, but droid is the core entrypoint for delegated work. At a high level:

• Inputs: Your repo, local files, optional prompt, optional tools (e.g., run tests)
• Process: The Droid plans the task, reads only what your permissions allow, manipulates files in a working tree, and prepares diffs/PRs
• Outputs: Code edits, added tests, documentation, or diagnostic artifacts—traceable back to your prompt and ticket context

Check the top-level help:

factory droid --help

You’ll see something like:

Usage:
  factory droid [flags]

Flags:
  -p, --prompt string   Task description for the Droid
  -f, --file string     Seed file or path to focus on
      --no-edit         Run read-only analysis (no file edits)
      --open-editor     Open changes in your editor after run
  ...

Flags vary by version, but the pattern is consistent: describe a task, optionally scope it, and let the Droid plan and execute.

---

Step 5: Run Your First droid Task

With the CLI installed and authenticated, you can run your first end-to-end task.

5.1 Choose or create a test repository

For your first run, use a sandbox repo so you can comfortably inspect changes:

mkdir factory-droid-demo
cd factory-droid-demo
git init
cat << 'EOF' > main.py
def add(a, b):
    return a + b

if __name__ == "__main__":
    print(add(2, 3))
EOF

git add main.py
git commit -m "Initial commit"

5.2 Ask a Droid to add tests

From the repo root:

factory droid \
  --prompt "Add a basic pytest suite for main.py, including edge cases for add()." \
  --file main.py

What happens under the hood:

• The Droid inspects main.py and the surrounding project layout
• It builds a lightweight plan (create test_main.py, import add, cover typical and boundary cases)
• It writes the new test file into your working tree
• It may optionally include instructions on running pytest, depending on your configuration

5.3 Review the changes

Inspect what the Droid did:

git status
git diff

You should see a new file like:

# test_main.py
from main import add

def test_add_basic():
    assert add(2, 3) == 5

def test_add_zero():
    assert add(0, 0) == 0

def test_add_negative():
    assert add(-1, 1) == 0

Run the tests to confirm:

pytest

This is the basic cycle: delegate → review → run → commit.

---

Step 6: A Second Task — Refactor with Guardrails

To see Factory’s “AI that will work with you, not replace you” philosophy, run a small refactor with clear constraints.

From the same repo:

factory droid \
  --prompt "Refactor add() in main.py to include type hints and a docstring. Do not change runtime behavior. Keep the CLI entrypoint intact." \
  --file main.py

Review the diff:

git diff

You’ll likely see:

• Type hints on the function signature
• A short docstring explaining arguments and return type
• No change to the if __name__ == "__main__": block

Because Droids work on your local tree:

• You control what gets committed
• Your org can export audit logs to a SIEM to track who ran what, where
• No changes are pushed or merged without your explicit action

---

Step 7: Using droid in Your Day-to-Day Workflow

Once you’re comfortable with droid, you can start using it for the work that usually eats your time.

In your IDE or terminal

Factory’s “Droids where you code” promise means:

• Run factory droid from your terminal inside VS Code, JetBrains, Vim, or any editor
• Keep your existing keybindings and tools; Droids work with your current workflow, not against it

Common terminal-native tasks:

• Bug investigations

  factory droid \
    --prompt "Investigate why add(-1, None) raises an error and propose a safe handling strategy. Suggest code changes but do not modify files yet." \
    --no-edit
  

• Documentation passes

  factory droid \
    --prompt "Add module-level and function-level docstrings to all Python files in this repo. Follow Google-style docstrings." 
  

• Small migrations

  factory droid \
    --prompt "Update all uses of add(a, b) to a new function add_numbers(a, b) while keeping behavior identical. Create add_numbers and maintain backwards compatibility with add()."
  

At scale via CLI

The same CLI primitives that power droid in your terminal can be scripted in CI/CD:

• Run Droids across many services for consistent refactors
• Parallelize work without centralizing all context in one place
• Maintain strict permissions with single-tenant, VPC-isolated execution

For your first day, keep it local and interactive. Once you trust the patterns, you can script them.

---

Security, Compliance, and Control Surfaces

When you install and run Factory’s CLI, you inherit the same enterprise controls your org enforces elsewhere:

• Strict permissions enforcement
  Droids only see code and tickets you already have access to in the source tools.

• Audit logging
  CLI runs can be logged and exported to your SIEM for traceability—what Droid ran, where, and with which prompts.

• Isolated compute
  Factory runs in a sandboxed, single-tenant environment with its own VPC. Traffic is encrypted in transit (TLS 1.2+) and at rest (AES-256).

• Clear IP stance
  Factory does not use your code as training data without prior written consent. Your code stays your code.

This matters because the CLI is powerful: it can touch real repos, write real diffs, and drive organization-wide processes. The controls make that power usable in production environments.

---

Troubleshooting Common Issues

A few quick checks if something doesn’t behave as expected:

factory: command not found

• Confirm installation directory:

  ls ~/.factory/bin
  

• Ensure it’s on PATH:

  echo $PATH | tr ':' '\n'
  

  If ~/.factory/bin is missing, add:

  echo 'export PATH="$HOME/.factory/bin:$PATH"' >> ~/.bashrc
  source ~/.bashrc
  

Authentication problems

• Re-run login:

  factory login
  factory whoami
  

• If SSO fails, confirm with your admin that CLI access is allowed in your IdP configuration.

No changes after running droid

• Confirm you’re in a Git repo root:

  git status
  

• Check if you accidentally passed --no-edit.

• Inspect logs or verbose output (--verbose if available in your version) to see if the Droid encountered tool or environment errors.

---

Next: Go Beyond Your First Task

Once you’ve installed Factory’s CLI and run your first droid task, you’re ready to start treating Droids as real teammates across your tooling surface:

• Droids where you code: Use factory droid from your IDE/terminal for focused refactors, tests, and docs.
• Droids in the browser: Use the web surface for ticket-centric work or deep overviews.
• Droids at scale (CLI): Script droid runs in CI/CD pipelines for migrations and maintenance.
• Droids in the war room: Connect Slack/Teams to pull Droids into incident channels.
• Droids in your backlog: Trigger Droids from project trackers to move tickets from “To Do” to PR.

The pattern is the same everywhere: delegate a complete task, keep your workflow, and retain full control over what ships.

Get Started