Skip to main content

Codely CLI Common Workflow Guide

This document covers common workflows for using Codely CLI in daily development, helping you leverage AI assistants more effectively to boost productivity.

Understanding New Codebases​

Quick Overview of the Codebase​

When you join a new project and need to quickly understand its structure and architecture:

  • Navigate to the project root directory
cd /path/to/project
  • Start Codely CLI
codely
  • Generate CODELY.md
/init general
# For Unity projects, use
# /init unity

Deep Dive into Specific Components​

What are the main architectural patterns used here?
What are the key data models?
How is authentication handled?

Tips:

  • Start with broad questions, then narrow down to specific areas
  • Ask about coding standards and patterns used in the project
  • Request a glossary of project-specific terminology

Resuming Previous Conversations with /resume​

When you need to locate code related to a specific feature or functionality:

  • Have Codely CLI search for related files
  • Get context information about how components interact
  • Understand the execution flow

Tips:

  • Clearly specify what you're looking for
  • Use domain language from the project

Efficient Bug Fixing​

When you encounter an error message and need to find and fix its source:

  1. Share the error information with Codely CLI
Running npm test gives the following error: [paste error message]
  1. Request fix suggestions
Suggest several ways to fix the @ts-ignore in user.ts
  1. Apply the fix
Update user.ts to add the null check you suggested

Tips:

  • Tell Codely CLI the command to reproduce the issue and get the stack trace
  • Mention any steps to reproduce the error
  • Let Codely CLI know if the error is intermittent or persistent

Refactoring Code​

When you need to update legacy code to use modern patterns and practices:

  1. Identify deprecated API usage in the codebase
Find deprecated API usage in our codebase
  1. Get refactoring suggestions
Suggest how to refactor utils.js to use modern JavaScript features
  1. Apply changes safely
Refactor utils.js to use ES 2024 features while maintaining the same behavior
  1. Verify refactoring results
Run tests for the refactored code

Tips:

  • Ask Codely CLI to explain the benefits of modern approaches
  • Request changes to maintain backward compatibility when needed
  • Refactor in small, testable increments

Using Specialized Sub-agents​

Codely CLI provides multiple specialized sub-agents to handle specific tasks more efficiently.

1. View Available Sub-agents​

/agents

This command displays all available sub-agents and allows you to create new sub-agents.

2. Automatic Sub-agent Usage​

Codely CLI will automatically delegate appropriate tasks to specialized sub-agents.

Review security issues in my recent code changes
Run all tests and fix any failures

3. Explicitly Request Specific Sub-agents​

Use the code-reviewer sub-agent to check the authentication module
Have the debugger sub-agent investigate why users cannot log in

4. Create Custom Sub-agents​

Create project-specific sub-agents in .codely-cli/agents/.

[agent]
id = "my-custom-agent"
description = "Agent specialized for handling X tasks"

[agent.system_prompt]
role = "You are a professional X expert"
behavior = "When encountering X-related tasks, you should..."

[agent.tools]
allowed = ["read_file", "write_file", "search_file_content"]

Tips:

  • Use descriptive description fields to enable automatic delegation
  • Restrict tool access to what each sub-agent actually needs
  • Create sub-agents in the project directory for team sharing

Writing Tests​

When you need to add tests for uncovered code:

  1. Identify untested code
Find functions in NotificationsService.swift that are not covered by tests
  1. Generate test scaffolding
Add tests for the notification service
  1. Add meaningful test cases
Add test cases for edge cases in the notification service
  1. Run and verify tests
Run the new tests and fix any failures

Codely CLI will:

  • Check your existing test files to match the style, framework, and assertion patterns already in use
  • Identify edge cases you might have missed
  • Suggest testing for error conditions, boundary values, and unexpected inputs that are easily overlooked

Creating Pull Requests​

When you need to create a well-documented pull request for your changes:

  1. Summarize your changes
  2. Use Codely CLI to generate a pull request
  3. Review and optimize
  4. Add test details

Tips:

  • Directly ask Codely CLI to create a PR for you
  • Review the PR generated by Codely CLI before submitting
  • Ask Codely CLI to highlight potential risks or considerations

Handling Documentation​

When you need to add or update documentation for your code:

  1. Identify undocumented code
  2. Generate documentation
  3. Review and enhance
  4. Verify documentation

Tips:

  • Specify the documentation style you want (JSDoc, docstrings, etc.)
  • Request examples in the documentation
  • Request documentation for public APIs, interfaces, and complex logic

Referencing Files and Directories​

Use @ to quickly include files or directories without waiting for Codely CLI to read them.

Reference a Single File​

Explain the logic in @src/utils/auth.js

This includes the complete content of the file in the conversation.

Reference a Directory​

This provides a directory listing showing file information.

What is the structure of @src/components?

Reference MCP Resources​

Show data from @github: repos/owner/repo/issues

This uses the format @server:resource to fetch data from connected MCP servers.

Tips:

  • File paths can be relative or absolute
  • @ file references add CODELY.md to the context from the file's directory and its parent directories
  • Directory references show file listings, not file contents
  • You can reference multiple files in a single message (e.g., @file1.js and @file2.js)

Resuming Previous Conversations​

Codely CLI provides two ways to resume previous conversations:

1. Continue the Most Recent Conversation​

codely --continue

This command will immediately resume your most recent conversation without any prompts.

2. Continue in Non-interactive Mode​

codely --continue --p "Continue my task"

Using --print and --continue together allows you to resume the most recent conversation in non-interactive mode, which is perfect for scripts or automation workflows.

3. Show Conversation Selector​

codely --resume

This command will display an interactive conversation selector, clearly listing the following information:

  • Session summary (or initial prompt)
  • Metadata: elapsed time, message count, and Git branch

Use arrow keys to navigate and press Enter to select a conversation. Press Esc to exit.

Tips:

  • Conversation history is stored on your local machine
  • Use --continue for quick access to the most recent conversation
  • Use --resume to select a specific historical conversation
  • Resumed conversations will use the same model and configuration as the original conversation

Running Parallel Sessions with Git Worktrees​

When you need to handle multiple tasks simultaneously and want each Codely CLI instance to have a completely independent code environment:

1. Understanding Git Worktrees​

Git worktrees allow you to check out multiple branches from the same repository into different directories. Each worktree has its own independent working directory and files, but shares the same Git history.

2. Create a New Worktree​

# Create a new worktree with a new branch
git worktree add ../project-feature-a -b feature-a

# Or create a worktree based on an existing branch
git worktree add ../project-bugfix bugfix-123

3. Run Codely CLI in Each Worktree​

# Navigate to your worktree directory
cd ../project-feature-a

# Run Codely CLI in this isolated environment
codely

4. Manage Your Worktrees​

# List all worktrees
git worktree list

# Remove worktree when done
git worktree remove ../project-feature-a

Tips:

  • Each worktree has its own independent file status, making it ideal for parallel Codely CLI sessions
  • Changes made in one worktree won't affect other worktrees
  • For long-running tasks, you can let Codely CLI work in one worktree while continuing development in another
  • Remember to initialize your development environment in each new worktree according to your project setup

Using Codely CLI as a Unix-style Tool​

Add to Validation Workflows​

Use Codely CLI as a linter or code review tool:

// package.json
{
  "scripts": {
    "lint:codely": "codely -p 'You are a linter. Please review the diff from the main branch and report any issues related to typos. Report the filename and line number on one line, and describe the issue on the next line. Do not return any other text.'"
  }
}

Tips:

  • Use Codely CLI in CI/CD pipelines for automated code review
  • Customize prompts to check for specific issues relevant to your project
  • Consider creating multiple scripts for different types of validation

Pipe Input, Pipe Output​

Stream data through Codely CLI:

cat build-error.txt | codely -p 'Concisely explain the root cause of this build error and summarize it to issue-troubleshooting.md'

Tips:

  • Use pipes to integrate Codely CLI into existing shell scripts
  • Combine with other Unix tools for powerful workflows
  • Consider using --output-format for structured output

Control Output Format​

Use --output-format to control the output format:

  • Text format (default)
cat data.txt | codely -p 'Summarize this data' --output-format text > summary.txt
  • JSON format
cat code.py | codely -p 'Analyze bugs in this code' --output-format json > analysis.json
  • Streaming JSON format
cat log.txt | codely -p 'Parse errors in this log file' --output-format stream-json

Unity Project Development Workflow​

First, you need to install Codely Bridge.

Codely CLI provides powerful Unity integration features, supporting interaction with Unity Editor through built-in tools and MCP servers.

Core Principles: State → Action → Verify → Correct​

  • State First - Before any write operations, call unity_editor.get_state to get the current state
  • Use Idempotent Operations - Prefer using ensure_* operations to ensure correct configuration
  • Compilation Verification - After script changes, must compile and verify 0 errors through the console
  • Confirm Changes - Confirm the new state after each write operation before continuing

Common Unity Workflows​

1. Creating and Modifying Scripts​

# Start Codely CLI
codely

# Create a new C# script
Create a script named PlayerController with basic movement control logic

# Modify existing script
Modify PlayerController.cs to add jump functionality

Verification process:

  • Codely CLI will automatically trigger compilation
  • Check Unity Console for errors
  • Continue only after confirming 0 errors

2. Scene Management​

Open Assets/Scenes/MainScene.unity
Create an empty GameObject named Player
Add Rigidbody component to Player
Save the scene

3. GameObject and Component Operations​

Create a Cube named Enemy
Add Mesh Collider to Enemy
Set Enemy's material to Assets/Materials/EnemyMat.mat
Move Enemy to position (0, 1, 0)

4. Asset Management​

Create a new material Assets/Materials/NewMaterial.mat
Set material color to red (1, 0, 0, 1)
Create a new prefab Assets/Prefabs/NewPrefab.prefab

5. NavMesh and Light Baking​

Ensure the scene is saved
Bake NavMesh
Bake lighting

6. Using Specialized Sub-agents​

Codely CLI provides Unity-specific sub-agents.

Use EditorModuleAgent to modify the UI system
Use EditorPlanAgent to generate execution plans
Use UnityCompileGateAgent to fix compilation errors

Unity Development Best Practices​

  • Always start with state - Call unity_editor.get_state before any write operations
  • Use ensure_ operations - Ensure idempotency of configuration
  • Verify after compilation - Script changes must verify 0 errors through Console
  • Save scene at critical boundaries - Save scene before baking, entering Play Mode
  • Avoid bulk re-imports - Use ensure_* instead of Assets/Reimport All
  • Follow Act → Confirm → Continue loop - Confirm state after each write operation

Asking Codely CLI About Its Features​

Codely CLI has built-in access to its documentation and can answer questions about its own features and limitations.

Example Questions​

  • Can Codely CLI create pull requests?
  • How does Codely CLI handle permissions?
  • What slash commands are available?
  • How do I use MCP with Codely CLI?
  • How do I configure Codely CLI for Amazon Bedrock?
  • What are the limitations of Codely CLI?
tip
  • Codely CLI always has access to the latest documentation
  • Ask specific questions for detailed answers
  • Codely CLI can explain complex features like MCP integration, enterprise configuration, and advanced workflows

Advanced Features​

Headless Mode​

Headless mode allows you to use Codely CLI in a non-interactive way, perfect for scripting and automation.

# Basic usage
codely -p "Your prompt"

# Read prompt from file
codely -f prompt.txt

# Pipe input
cat input.txt | codely -p "Analyze the following content"

# Specify output format
codely -p "Analyze code" --output-format json

# Use specific model
codely -p "Your prompt" --model qwen-max

# Resume previous conversation
codely --continue -p "Continue the previous task"

Approval Mode​

Approval mode requires your confirmation before Codely CLI executes certain operations.

codely --approval-mode

In approval mode, Codely CLI will request confirmation before:

  • Modifying the file system
  • Running shell commands
  • Executing git operations
  • Other potentially dangerous operations

MCP Server Integration​

Codely CLI supports MCP (Model Context Protocol) servers, allowing you to extend its capabilities.

# Start Unity MCP server
npm run unity-mcp

# Use MCP resources
Show data from @unity: scene/active
Show data from @github: repos/owner/repo/issues

Summary​

Codely CLI is a powerful AI-driven command-line tool that can significantly improve your development productivity. By mastering these common workflows, you can:

  • Quickly understand new codebases
  • Efficiently find and fix bugs
  • Safely refactor code
  • Automate test writing
  • Simplify PR creation workflows
  • Manage Unity projects

Remember These Key Principles​

  • Start with understanding - First understand the codebase structure and conventions
  • Use specialized tools - Leverage sub-agents and built-in tools
  • Verify every change - Run tests, lint, and type checks
  • Maintain context - Use @ references and conversation recovery features

Enjoy using Codely CLI!

  • PS. We have released a CLI nightly version that includes the latest features. Welcome to try it out!-