# YepCode Command Line Interface Rules

> Comprehensive guidelines for AI agents to use YepCode CLI for local development, testing, and synchronization with YepCode Cloud.

Comprehensive guidelines for AI agents to use YepCode CLI for local development, testing, and synchronization with YepCode Cloud.

[Download this file](/docs/ai-rules/cli.md)

## What is YepCode CLI?

[Section titled “What is YepCode CLI?”](#what-is-yepcode-cli)

The YepCode CLI facilitates interaction with YepCode Cloud directly from your local workstation’s command line. It’s particularly useful for developing and testing processes locally.

## Command Flow

[Section titled “Command Flow”](#command-flow)

**When making changes and testing:**

1. Optionally run `yepcode pull` first if the user (or someone else) may have changed resources in YepCode Cloud, so you work with the latest version.
2. Make changes to local files (processes, modules, variables, etc.)
3. Run `yepcode add` **only when you have created NEW resources** (new process, new module, new dependency, or new variable). For updates to existing process or module code, skip this step.
4. Run `yepcode dependencies:install` if you have changed dependencies in the local dependencies folder (dependencies/package.json or dependencies/requirements.txt)
5. Run `yepcode run` to test (execute the process locally for development/testing purposes)
6. Run `yepcode push` to deploy to cloud (when ready for production synchronization). Run after any local changes; run `yepcode add` first if you added new resources in step 3.

## Core CLI Commands

[Section titled “Core CLI Commands”](#core-cli-commands)

### `yepcode add`

[Section titled “yepcode add”](#yepcode-add)

**Purpose**: Register **new** local resources (new process, new module, new dependency, or new variable) with the CLI so they can be executed or deployed. It may fix the error “Local process not found” when you have just created that process.

**Usage**:

```sh
yepcode add
```

**When to use**:

* After creating a **new** process, **new** module, **new** dependency, or **new** variable
* Before running `yepcode run` or `yepcode push` when such new resources exist

**When not to use**:

* After only updating existing process or module code (use `yepcode push` directly)
* After only updating existing variables (use `yepcode push` directly)

**What it does**:

* Registers new resources in the local workspace
* Makes new processes/modules/variables/dependencies ready for run or push

**Important**: Run `yepcode add` when you have **new** resources; for existing resources, `yepcode push` is enough.

### `yepcode dependencies:install`

[Section titled “yepcode dependencies:install”](#yepcode-dependenciesinstall)

**Purpose**: Install dependencies in the local workspace.

**Usage**:

```sh
yepcode dependencies:install
```

**When to use**:

* After changing dependencies in the local dependencies folder (dependencies/package.json or dependencies/requirements.txt)

**What it does**:

* Installs dependencies in the local workspace

### `yepcode run <process-slug> --parameters <filepath | stringified-json>`

[Section titled “yepcode run \<process-slug> --parameters \<filepath | stringified-json>”](#yepcode-run-process-slug---parameters-filepath--stringified-json)

**Purpose**: Execute a process locally for development/testing

**Usage**:

```sh
# Using a parameters file
yepcode run <process-slug> --parameters <filepath>


# Using stringified JSON
yepcode run <process-slug> --parameters '{"key": "value"}'


# Using default parameters.json from process folder
yepcode run <process-slug>
```

**When to use**:

* To test process execution locally
* To debug issues with detailed logs
* During iterative development to validate changes

**What it does**:

* Executes the process code locally
* Uses environment variables from `variables.env` and `variables.local.env`
* Uses provided parameters or default `parameters.json`
* Shows execution logs
* Shows execution results and errors (if any)

**Prerequisites**:

* Run `yepcode add` first if the process (or other resource) was just created

### `yepcode pull`

[Section titled “yepcode pull”](#yepcode-pull)

**Purpose**: Sync changes from YepCode Cloud to your local workspace.

**Usage**:

```sh
yepcode pull
```

**When to use**:

* Before starting work if others may have changed resources in the cloud
* When the user has made changes in YepCode Cloud and you need the latest version locally
* When you want to discard local changes and match the cloud state

**What it does**:

* Downloads the latest processes, modules, variables, and dependencies from the cloud
* Updates your local files to match the cloud

**Force pull**: If both local and cloud have changes, pull may fail. Use the `--force` flag only when intended, and **always ask for user confirmation** before using force.

### `yepcode push`

[Section titled “yepcode push”](#yepcode-push)

**Purpose**: Deploy local changes to YepCode cloud

**Usage**:

```sh
yepcode push
```

**When to use**:

* When the process is ready for production
* After testing locally with `yepcode run`
* To make changes available in the cloud

**What it does**:

* Uploads local files to YepCode cloud
* Updates cloud resources with local changes
* Makes the process available for cloud execution

**Prerequisites**:

* Run `yepcode add` first if you created new resources (new process, module, dependency, or variable)
* Recommended to run `yepcode run` first to test

**Force push**: If both local and cloud have changes, push may fail. Use the `--force` flag only when the user intends to overwrite cloud with local; **always ask for user confirmation** before using force.

## Complete Workflow Examples

[Section titled “Complete Workflow Examples”](#complete-workflow-examples)

### Example 1: Development Cycle

[Section titled “Example 1: Development Cycle”](#example-1-development-cycle)

**Agent**: “I’ve implemented the script. Would you like to test it locally?”

**User**: “Yes”

**Agent**: “I’ll sync and run it for you.”

*\[Agent runs yepcode add]* *\[Agent runs yepcode dependencies:install]* *\[Agent runs yepcode run]*

**Agent**: “The logs look good! Would you like to push to production?”

**User**: “Yes”

**Agent**: “Deploying to production now.”

*\[Agent runs yepcode push (no need to run yepcode add again since nothing changed)]*

### Example 2: Testing a New Process

[Section titled “Example 2: Testing a New Process”](#example-2-testing-a-new-process)

**User**: “I need to test the new shopify-order-sync process locally with some parameters”

**AI**: “I’ll add the process first and then run it for you.”

```sh
yepcode add
```

Install dependencies if needed:

```sh
yepcode dependencies:install
```

```sh
yepcode run shopify-order-sync --parameters '{"dateFrom": "2024-01-01", "dateTo": "2024-01-31"}'
```

### Example 3: Deploying to Production

[Section titled “Example 3: Deploying to Production”](#example-3-deploying-to-production)

**User**: “The inventory-sync process is ready for production. Please deploy it to the cloud.”

**AI**: “I’ll sync the process and push it to production.”

```sh
yepcode add
```

```sh
yepcode push
```

## Critical Rules

[Section titled “Critical Rules”](#critical-rules)

* **Run `yepcode add`** when you have created **new** resources (new process, module, dependency, or variable); then run `yepcode run` or `yepcode push` as needed.
* **Run `yepcode push`** after any local changes to sync to cloud; run `yepcode add` first only if new resources were created.
* **Run `yepcode pull`** before making changes when the user or others may have updated resources in the cloud.
* **NEVER run `yepcode run`** without having run `yepcode add` first when the process (or other resource) was just created.
* **Ask for user confirmation** before using `--force` on `yepcode push` or `yepcode pull`.