Skip to main content

🖥️ Running Early CLI Locally

You can run the Early CLI manually on your machine to evaluate test generation before integrating it into your CI/CD. This is useful for:

  • Testing how Early handles a specific folder or branch
  • Validating your API key and token permissions
  • Previewing generated test files in your IDE
  • Running offline or experimental workflows

1️⃣ Getting Ready​

Before running the CLI locally, make sure you're set up with the following.

You’ll need these mandatory parameters to run the CLI successfully:

early generate-for-project \
  --api-key <your_api_key> \
  --token <your_github_token> \
  --target-directory <path_to_file_or_directory> \
  --ref-name <branch_name>

The --target-directory flag accepts either a directory or a single file. This allows you to generate tests for a specific file instead of scanning an entire folder.

Now, let’s make sure you have everything ready to execute this command.

✅ 1. Install the CLI​

Install the CLI globally via npm:

npm install -g @earlyai/cli

🔑 2. API Key from Early​

You should have received an API key from the Early team.
If not, contact support@startearly.ai to get one.

Store it securely — it will be used as --api-key.

🔐 3. GitHub Personal Access Token (PAT)​

Create a classic or fine-grained GitHub token to use with --token.

Classic PAT requirements:

  • Scope: repo, read:packages

Fine-grained PAT requirements:

  • Access to your repo
  • Permissions:
    • Contents: Read & Write
    • Pull Requests: Read & Write
    • Metadata: Read

Create one here:
https://github.com/settings/tokens

Store it securely — it will be passed as --token.

🌿 4. Create a Dedicated Branch​

To avoid unintentionally committing generated files to your default branch (e.g., main),
it’s recommended to create a separate branch first:

git checkout -b early-cli-local-run

Then use that branch name with the --ref-name flag.

▶️ Step 2: Run the CLI​

This command runs test generation on a folder named src/user-usage/ using an API key and token:

early generate-for-project \
  --api-key xxxxx \
  --token github_pat_123456 \
  --target-directory src/user-usage/ \
  --ref-name cli-repo-run-1125

Run on a single file

early generate-for-project \
  --api-key xxxxx \
  --token github_pat_123456 \
  --target-directory src/utils/math.ts \
  --ref-name cli-repo-single-file

📄 Step 3: What Logs Will I See?​

Here's a sample log from a successful run:

🧪 **Early Pull Request Test Generation Agent**

- Changed files: 11
- Files with testable code: 4
- Total methods detected: 18
- Public methods below coverage threshold: 3

**Action Taken**

✅ Unit tests automatically generated for 3 public functions below threshold.  
📦 Test files have been auto-committed to this branch.

📊 PR coverage before: 71%. PR coverage after: 91%.

📦 Where Are My Test Files?​

If you leave --auto-commit at its default (true), test files are committed directly to your current branch. You can see them in your Git history or IDE.

To find them manually:

  • Check the tests/ folder (if you're using rootFolder structure)
  • Or look beside the original source files (for siblingFolder structure)

👀 Want to See Files in the IDE Before Committing?​

Use the same command with --auto-commit false:

early generate-for-project \
  --api-key xxxxx \
  --token github_pat_123456 \
  --target-directory src/user-usage/ \
  --ref-name cli-repo-run-1125 \
  --auto-commit false

This will leave the generated test files unstaged so you can explore or edit them in your IDE before committing manually.

running locally

✅ Run a Quick Test First​

To begin, try pointing the CLI at one file in your project — for example:

early generate-for-project \
  --api-key <your_api_key> \
  --token <your_token> \
  --target-directory src/utils/math.ts \
  --ref-name my-local-run

This helps validate that everything is configured correctly before scanning larger areas.

❌ See an error?​

Check out the Troubleshooting Guide in this chapter for help resolving:

  • CLI not installing
  • Missing API key or token
  • Memory issues
  • Push conflicts
  • And more...

🕵️ No tests were generated?​

If the CLI runs but you don’t see any tests created, it could be due to a number of reasons —
see Why No Tests Were Generated → for a step-by-step checklist.