Push & Pull Configuration
The Serval CLI enables you to manage your workspaceβ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:- 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
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:
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:
Finding Your Workspace Prefix
To work with a workspaceβs workflows, you need its prefix. You can find workspace prefixes by:- Visiting admin settings in Serval
- Navigating to the Workspaces section
- Looking for the workspace prefix (e.g.,
EXA,DEV,OPS)
Pulling Workflows and Skills
To download a workspaceβs workflows, skills, and configuration:Directory Structure
- teams/: Holds one directory per workspace you have pulled
- Workspace Directory: Named after the workspace prefix (e.g.,
EXA/) - team.yaml: Contains workspace-level metadata and configuration
- workflows/: Contains all workflows for the workspace
- Workflow Folders: Each workflow has its own directory with:
index.ts: The TypeScript implementation of the workflowworkflow.yaml: Workflow metadata and configuration
- skills/: Contains all Help Desk and Catalyst skills for the workspace
- Skill Folders: Each skill has its own directory with:
SKILL.md: The instructions the agent follows, written in Markdownskill.yaml: Skill metadata
Workflow Metadata (workflow.yaml)
Each workflow includes aworkflow.yaml file with the following structure:
- 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
For a workflow that uses a reusable approval procedure,
approval_procedure shows only the approvers the CLI supports in each step: specific users, groups and self-approval. Manager, app owner and custom workflow approvers, secondary approvers and group minimums donβt appear, so check Settings β Approval Procedures for the full procedure. Pushing a change to those steps, or removing them, fails. Edit the procedure in Settings β Approval Procedures, or choose a different procedure on the workflow.Skill Metadata (skill.yaml)
Each skill has aSKILL.md file with the instructions the agent follows, written in Markdown, and a skill.yaml file with the following structure:
- 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_deskfor a Help Desk Skill orcatalystfor 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
deployedinworkflow.yaml - id: Server-managed identifier that the CLI uses to match your local skill to the one in Serval
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.tsfile to change workflow behavior - Update metadata: Modify
workflow.yamlto change description, approval procedures, etc. - Modify skill instructions: Edit
SKILL.mdto change what the agent does, andskill.yamlto 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:- 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 byidor name - Modified skills: Name, description, instructions, and always-use changes are pushed; when
deployedis true and the name, description, or instructions changed, the new version is published - Unpublishing skills: Setting
deployed: falseon 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
Working with Multiple Workspaces
You can manage workflows and skills for multiple workspaces: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:--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:
-
Use branches for workflow changes:
Development Workflow
-
Pull latest: Always pull before making changes
- Make changes: Edit workflows locally
- Test: Validate your TypeScript code
- Commit: Save changes to version control
-
Push: Deploy to Serval

