> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Push & Pull Configuration

> Managing Serval workflows locally with the CLI

# Push & Pull Configuration

The Serval CLI enables you to manage your team's workflows locally, allowing you to use your preferred development tools and integrate with version control systems like Git.

## Authentication

Before you can pull or push workflows, you need to authenticate with Serval:

```bash theme={null}
serval login
```

This will initiate a device authentication flow:

1. The CLI will display a device code and URL
2. Visit the URL in your browser (e.g., `https://app.serval.com/auth/device?code=XXXX-1234`)
3. Confirm the authentication in your browser
4. The CLI will automatically detect successful authentication

Example output:

```
🔐 Device Authentication Required
================================
Please visit the Serval web app at https://app.serval.com/auth/device?code=XXXX-1234
Waiting for authorization...
✅ Successfully authenticated!
```

To check your authentication status:

```bash theme={null}
serval status
```

To log out:

```bash theme={null}
serval logout
```

## Finding Your Team Prefix

To work with a team's workflows, you need its prefix. You can find team prefixes by:

1. Visiting [admin settings](https://app.serval.com/admin/settings) in Serval
2. Navigating to the **Teams** section
3. Looking for the team prefix (e.g., `EXA`, `DEV`, `OPS`)

The prefix is also included in the URL when you visit a team's workflows or tickets in the web app.

## Pulling Workflows

To download a team's workflows and configuration:

```bash theme={null}
serval pull <team-prefix>
```

For example:

```bash theme={null}
serval pull EXA
```

This creates a local directory structure:

```
EXA/                         # Team directory
├── team.yaml               # Team metadata
└── workflows/              # All workflows for this team
    ├── hello-world/
    │   ├── index.ts       # Workflow implementation
    │   └── workflow.yaml  # Workflow metadata
    └── onboard-employee/
        ├── index.ts
        └── workflow.yaml
```

### Directory Structure

* **Team Directory**: Named after the team prefix (e.g., `EXA/`)
* **team.yaml**: Contains team-level metadata and configuration
* **workflows/**: Contains all workflows for the team
* **Workflow Folders**: Each workflow has its own directory with:
  * `index.ts`: The TypeScript implementation of the workflow
  * `workflow.yaml`: Workflow metadata and configuration

### Workflow Metadata (workflow\.yaml)

Each workflow includes a `workflow.yaml` file with the following structure:

```yaml theme={null}
name: Hello World
description: This is the workflow description.
slug: hello-world
deployed: true
approval_procedure:
    steps:
        - step_type: groups
          group_ids:
            - 01959d51-dcfg-7dfc-9e9b-742237d518c7
version: 1
```

Key fields:

* **name**: Display name of the workflow
* **description**: Detailed description of what the workflow does
* **slug**: URL-friendly identifier (must match the folder name)
* **deployed**: Whether the workflow is active in Serval
* **approval\_procedure**: Defines who can approve workflow runs
* **version**: Workflow version number

## Editing Workflows

Once pulled, you can edit workflows using any text editor or IDE:

1. **Modify workflow code**: Edit the `index.ts` file to change workflow behavior
2. **Update metadata**: Modify `workflow.yaml` to change description, approval procedures, etc.
3. **Test locally**: Use your standard TypeScript development tools
4. **Version control**: Commit changes to Git or your preferred VCS

## Pushing Changes

After making local changes, push them back to Serval:

```bash theme={null}
serval push <team-prefix>
```

For example:

```bash theme={null}
serval push EXA
```

The CLI will:

1. Validate your local changes
2. Compare with the remote state
3. Upload modified workflows
4. Update workflow versions
5. Deploy changes if `deployed: true`

### Push Behavior

* **New workflows**: Created if they don't exist in Serval
* **Modified workflows**: Updated with your changes
* **Deleted workflows**: Not automatically deleted (manual deletion required in UI)
* **Validation**: The CLI validates YAML syntax and basic structure before pushing

## Working with Multiple Teams

You can manage workflows for multiple teams:

```bash theme={null}
# Pull workflows from different teams
serval pull EXA
serval pull DEV
serval pull OPS

# Your directory structure will be:
# EXA/
#   └── workflows/
# DEV/
#   └── workflows/
# OPS/
#   └── workflows/
```

## Best Practices

### Version Control

1. **Initialize Git** in your workflow directory:
   ```bash theme={null}
   git init
   cd EXA
   git add .
   git commit -m "Initial workflow commit"
   ```

2. **Use branches** for workflow changes:
   ```bash theme={null}
   git checkout -b update-onboarding-workflow
   # Make changes
   git commit -m "Add manager approval to onboarding"
   # Review and merge in your VCS
   # After merging, push to Serval
   serval push EXA
   ```

### Development Workflow

1. **Pull latest**: Always pull before making changes
   ```bash theme={null}
   serval pull EXA
   ```

2. **Make changes**: Edit workflows locally

3. **Test**: Validate your TypeScript code

4. **Commit**: Save changes to version control

5. **Push**: Deploy to Serval
   ```bash theme={null}
   serval push EXA
   ```