Push & Pull Configuration

The Serval CLI enables you to manage your team’s workflows and skills 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:

serval login

This will initiate a device authentication flow:

The CLI will display a device code and URL
Visit the URL in your browser (e.g., https://app.serval.com/auth/device?code=XXXX-1234)
Confirm the authentication in your browser
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!

Signing in to another region

serval login signs you in to the United States region. If your organization uses the European Union region, pass its application URL:

serval login --url https://app.eu1.serval.com

The CLI saves that URL in your profile after you sign in, so pull, push, and access reach the right region without repeating the flag. This requires CLI v0.5.7 or later. Earlier versions resolve the wrong API host and fail at sign-in with a no such host error, so run serval version if you are unsure. Data residency lists the regions Serval operates and the application URL of each. To check your authentication status:

serval status

To log out:

serval logout

Finding Your Team Prefix

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

Visiting admin settings in Serval
Navigating to the Teams section
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. When environments are enabled, you can use a non-live environment’s prefix or the prefix of a branch you have access to. Pull and push still require the permissions for that team.

Pulling Workflows and Skills

To download a team’s workflows, skills, and configuration:

serval pull <team-prefix>

For example:

serval pull EXA

This creates a local directory structure:

teams/
└── 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
    └── skills/                   # All Help Desk and Catalyst skills for this team
        ├── resetting-passwords/
        │   ├── SKILL.md          # Skill instructions
        │   └── skill.yaml        # Skill metadata
        └── reviewing-workflows/
            ├── SKILL.md
            └── skill.yaml

Directory Structure

teams/: Holds one directory per team you have pulled
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
skills/: Contains all Help Desk and Catalyst skills for the team
Skill Folders: Each skill has its own directory with:
- SKILL.md: The instructions the agent follows, written in Markdown
- skill.yaml: Skill metadata

Workflow Metadata (workflow.yaml)

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

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

Skill Metadata (skill.yaml)

Each skill has a SKILL.md file with the instructions the agent follows, written in Markdown, and a skill.yaml file with the following structure:

name: Resetting Passwords
description: Resets a user's password. Use when a requester says they are locked out or forgot their password.
slug: resetting-passwords
skill_type: help_desk
should_always_use: false
deployed: true
id: 019f8c14-770d-76cb-a76a-a20040e8564c

Key fields:

name: Display name of the skill, written as a title with spaces
description: When the agent should use this skill. Leave it empty for an always-use skill
slug: Folder name for the skill (must match the folder name)
skill_type: help_desk for a Help Desk Skill or catalyst for a Catalyst Skill
should_always_use: Whether the skill applies on every turn instead of only when it matches a request
deployed: Whether the version you pulled is the one the agent uses, the same meaning as deployed in workflow.yaml
id: Server-managed identifier that the CLI uses to match your local skill to the one in Serval

References to workflows, other skills, users, and entitlements inside SKILL.md use the same mention syntax as the web editor, for example <@workflow:wf_...>.

Editing Workflows and Skills

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

Modify workflow code: Edit the index.ts file to change workflow behavior
Update metadata: Modify workflow.yaml to change description, approval procedures, etc.
Modify skill instructions: Edit SKILL.md to change what the agent does, and skill.yaml to change the name, description, or always-use setting
Test locally: Use your standard TypeScript development tools
Version control: Commit changes to Git or your preferred VCS

Pushing Changes

After making local changes, push them back to Serval:

serval push <team-prefix>

For example:

serval push EXA

The CLI will:

Validate your local changes
Compare with the remote state
Upload modified workflows and skills
Update workflow versions
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)
New skills: Created when a skills/<slug>/ folder matches no existing skill by id or name
Modified skills: Name, description, instructions, and always-use changes are pushed; when deployed is true and the name, description, or instructions changed, the new version is published
Unpublishing skills: Setting deployed: false on a live skill does not unpublish it; unpublish from the web app
Deleted skills: Not automatically deleted (manual deletion required in UI)
Validation: The CLI validates YAML syntax and basic structure before pushing

Pulling skills requires the team Viewer role or higher. Editing skills requires Drafter, and publishing them requires Builder.

Working with Multiple Teams

You can manage workflows and skills for multiple teams:

# Pull workflows and skills from different teams
serval pull EXA
serval pull DEV
serval pull OPS

# Your directory structure will be:
# teams/
#   ├── EXA/
#   │   ├── workflows/
#   │   └── skills/
#   ├── DEV/
#   │   ├── workflows/
#   │   └── skills/
#   └── OPS/
#       ├── workflows/
#       └── skills/

Profiles

Each profile stores the credentials and platform URL of a single organization. If you work in more than one, give each its own profile:

serval login --profile acme
serval login --profile acme-eu --url https://app.eu1.serval.com

Signing in makes that profile active. To see your profiles and switch between them:

serval profile list           # name, organization, URL, and token status
serval profile use acme-eu    # set the active profile
serval profile show           # details for the active profile
serval profile remove acme    # remove a profile

Every command accepts --profile <name> to select a profile for a single run, and the SERVAL_PROFILE environment variable sets it for a shell session.

Best Practices

Version Control

Initialize Git in your workflow directory:

git init
cd EXA
git add .
git commit -m "Initial workflow commit"

Use branches for workflow changes:

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

Pull latest: Always pull before making changes
serval pull EXA
Make changes: Edit workflows locally
Test: Validate your TypeScript code
Commit: Save changes to version control
Push: Deploy to Serval
serval push EXA

​Push & Pull Configuration

​Authentication

​Signing in to another region

​Finding Your Team Prefix

​Pulling Workflows and Skills

​Directory Structure

​Workflow Metadata (workflow.yaml)

​Skill Metadata (skill.yaml)

​Editing Workflows and Skills

​Pushing Changes

​Push Behavior

​Working with Multiple Teams

​Profiles

​Best Practices

​Version Control

​Development Workflow