Command Reference

Overview

It is still in experimental phase and is not yet complete. In case of any issues, please reach out to us on Discord or email.

The julep CLI is a comprehensive command-line interface for interacting with the Julep platform. Following are the available commands.

Authentication

Basic
With API Key
With Environment

julep auth

The julep auth command is used to authenticate your Julep CLI. This will prompt you to enter your API key and save it to the configuration file.Example:

# Basic authentication with interactive prompt
julep auth

# Output:
# Enter your Julep API key: **********************
# Authentication successful!

julep auth --api-key your_julep_api_key

The julep auth --api-key your_julep_api_key command is used to authenticate your Julep CLI with a specific API key.

string

required

Your Julep API key

Examples:

# Authenticate with API key directly
julep auth --api-key "julep_1234567890abcdef"

# Using environment variable
export JULEP_API_KEY="julep_1234567890abcdef"
julep auth --api-key $JULEP_API_KEY

julep auth --api-key your_key --environment staging

The julep auth --api-key your_key --environment staging command is used to authenticate your Julep CLI with a specific API key and environment.

string

required

Your Julep API key

string

required

Environment to use (production/staging)

Examples:

# Authenticate with staging environment
julep auth --api-key "julep_1234567890abcdef" --environment staging

# Authenticate with production environment
julep auth --api-key "julep_1234567890abcdef" --environment production

# Using environment variables
export JULEP_API_KEY="julep_1234567890abcdef"
export JULEP_ENV="staging"
julep auth --api-key $JULEP_API_KEY --environment $JULEP_ENV

You can get your API key from the Julep Dashboard.

Project Management

Initialize
Sync
Import

julep init --template "Template Name" --path "Destination Path" --yes

The julep init command is used to initialize a new Julep project using a predefined template. You can check the list of available templates in our library.

string

required

Name of the template to use from the library repository (default: “hello-world”)

string

Destination directory for where you want to initialize the project (default: current directory)

boolean

Skip confirmation prompt

Examples:

# Initialize a project with the default template (hello-world template)
julep init

# Initialize a project with a specific template
julep init --template "profiling-recommending" --path "./my-project" # Will be initialized in ./my-project/profiling-recommending

# Initialize a project and skip confirmation
julep init --yes

julep sync [--force-local] [--force-remote] [--source "Source Path"]

The julep sync command is used to synchronize the local project with the Julep platform.

boolean

Force local files to take precedence

boolean

Force remote state to take precedence

boolean

Watch for changes and synchronize automatically.

Note: when watch mode is enabled, only local-to-remote sync force-local is supported. Use --force-remote only with watch mode turned off.

string

Source directory to sync from (default: current directory)

Examples:

# Basic sync
julep sync

# Force local changes to override remote
julep sync --force-local

# Force remote state to override local
julep sync --force-remote

# Sync with specific source directory
julep sync --source ./my-project

# Watch for changes and synchronize automatically
julep sync --watch

julep import --agent --id agent_id --output path

The julep import command is used to import an agent, task, or tool from the Julep platform.

Note: Importing tasks and tools is not yet supported; only agents are supported.

boolean

required

Specify that you want to import an agent

string

required

ID of the agent to import

string

Path to the source directory. Defaults to current working directory

string

Path to save the imported agent (default: <source_dir>/src/agents/<agent-name>.yaml)

boolean

Skip confirmation prompt

Examples:

# Import agent to default directory
julep import --agent --id "00000000-0000-0000-0000-000000000000"

# Import agent with specific filename
julep import --agent --id "00000000-0000-0000-0000-000000000000" --output ./agents/my-agent.yaml

# Import agent and skip confirmation
julep import --agent --id "00000000-0000-0000-0000-000000000000" --yes

Task Execution

Run
Logs

julep run --task <task_id> --input '{"key": "value"}'

The julep run command is used to execute a task.

string

required

ID of the task to execute

json

Input data for the task

string

Path to a json file containing the input to execute the task with

boolean

Wait for the task to complete before exiting, stream logs to stdout

Examples:

# Run task with inline JSON input
julep run --task "00000000-0000-0000-0000-000000000000" --input '{"prompt": "Write a story about a magical forest"}'

# Run task with input from file
julep run --task "00000000-0000-0000-0000-000000000000" --input-file ./inputs/story-params.json

# Run task and wait for completion
julep run --task "00000000-0000-0000-0000-000000000000" --input '{"style": "watercolor"}' --wait

# Run task that doesn't require input (empty object)
julep run --task "00000000-0000-0000-0000-000000000000" --input '{}'

# Invalid task ID
julep run --task bad-id --input '{}'
# -> Error creating execution: Task not found

julep logs --execution-id exec_id [--tail]

The julep logs command is used to view execution logs.

string

required

ID of the execution to view logs for

boolean

Continuously stream logs as they are generated

Examples:

# View logs for a specific execution
julep logs --execution-id "00000000-0000-0000-0000-000000000000"

# Stream logs in real-time
julep logs --execution-id "00000000-0000-0000-0000-000000000000" --tail

# Get logs in JSON format
julep logs --execution-id "00000000-0000-0000-0000-000000000000" --json

Agent Management

The commands in julep agents are used to manage your agents.

Create
Update
Delete
List
Get

julep agents create --name "Agent Name" \
                   --model "Model Name" \
                   --about "Agent Description" \
                   --metadata '{"key": "value"}' \
                   --instructions "Instruction"

The julep agents create command is used to create a new agent.

string

required

Name of the agent

string

Model to be used (e.g., gpt-4). You can find the list of models here

string

Description of the agent

json

Additional metadata (JSON format)

string

Instructions for the agent (can be repeated)

string

Path to agent definition file

Examples:

# Create a basic agent
julep agents create --name "Story Writer" --model "gpt-4"

# Create agent with full configuration
julep agents create \
  --name "Content Assistant" \
  --model "gpt-4" \
  --about "AI assistant for content creation" \
  --metadata '{"type": "content", "version": "1.0"}' \
  --instructions "Focus on creative writing" \
  --instructions "Maintain professional tone"

# Create agent from definition file
julep agents create --definition ./agents/content-assistant.yaml

Note: When creating an agent, the agent doesn’t get automatically imported to the project. You can run julep import --agent --id <agent-id> to import the agent to the project.

julep agents update --id agent_id \
                   --name "New Name" \
                   --model "New Model"

The julep agents update command is used to update an existing agent.

string

required

ID of the agent to update

string

New name for the agent

string

New model for the agent

string

New description for the agent

json

Additional metadata (JSON format)

array

New instructions for the agent (can be repeated)

Examples:

# Update agent name
julep agents update --id "agent_abc123" --name "Enhanced Writer"

# Update multiple properties
julep agents update \
  --id "agent_abc123" \
  --name "Content Pro" \
  --model "gpt-4" \
  --about "Professional content creation assistant"

# Update metadata
julep agents update \
  --id "agent_abc123" \
  --metadata '{"type": "content", "version": "2.0"}'

# Update instructions
julep agents update \
  --id "agent_abc123" \
  --instructions "New instruction 1" \
  --instructions "New instruction 2"

# Update from definition file
julep agents update --id "agent_abc123" --definition ./agents/updated-agent.yaml

julep agents delete --id agent_id [--force]

The julep agents delete command is used to delete an existing agent.

string

required

ID of the agent to delete

boolean

Skip confirmation prompt

Examples:

# Delete with confirmation prompt
julep agents delete --id "00000000-0000-0000-0000-000000000000"

# Force delete without confirmation
julep agents delete --id "00000000-0000-0000-0000-000000000000" --force

# Delete multiple agents using a bash for loop
for id in agent_id1 agent_id2 agent_id3; do
  julep agents delete --id "$id" --force
done

julep agents list [--metadata-filter '{"key": "value"}'] [--json]

The julep agents list command is used to list all agents.

json

Filter agents by metadata

boolean

Output in JSON format

Examples:

# List all agents
julep agents list

# List agents with JSON output
julep agents list --json

# Filter agents by metadata
julep agents list --metadata-filter '{"type": "content"}'

# List agents and process with jq
julep agents list --json | jq '.[] | select(.model=="gpt-4")'

# Save agent list to file
julep agents list --json > agents.json

julep agents get --id agent_id [--json]

The julep agents get command is used to get details of a specific agent.

string

required

ID of the agent to retrieve

boolean

Output in JSON format

Examples:

# Get agent details
julep agents get --id "agent_abc123"

# Get agent details in JSON format
julep agents get --id "agent_abc123" --json

# Save agent details to file
julep agents get --id "agent_abc123" --json > agent.json

# Get and process with jq
julep agents get --id "agent_abc123" --json | jq '.instructions'

Task Management

Create
Update
Delete
List
Get

julep tasks create --name "Task Name" \
                  --agent-id agent_id \
                  --definition path/to/task.yaml \
                  --metadata '{"status": "beta"}' \
                  --inherit-tools

The julep tasks create command is used to create a new task.

string

required

ID of the associated agent

string

Name of the task

string

Path to task definition file

json

Additional metadata (JSON format)

boolean

Inherit tools from agent

string

Import to project after creating

julep tasks update --id task_id \
                  --name "New Name" \
                  --agent-id new_agent_id \
                  --definition new/path/to/task.yaml

The julep tasks update command is used to update an existing task.

string

required

ID of the task to update

string

New name for the task

string

New agent ID for the task

string

Path to new task definition file

string

New description for the task

json

New metadata for the task

boolean

Whether to inherit tools from the agent

julep tasks delete --id task_id [--force]

The julep tasks delete command is used to delete an existing task.

string

required

ID of the task to delete

boolean

Skip confirmation prompt

julep tasks list [--agent-id agent_id] [--json]

The julep tasks list command is used to list all tasks.

string

Filter by associated agent ID

boolean

Output in JSON format

julep tasks get --id task_id [--json]

The julep tasks get command is used to get details of a specific task.

string

required

ID of the task to retrieve

boolean

Output in JSON format

Tool Management

Create
Update
Delete
List

julep tools create --name "Tool Name" \
                  --type tool_type \
                  --agent-id agent_id \
                  --definition path/to/config.yaml

The julep tools create command is used to create a new tool.

string

required

ID of the associated agent

string

required

Name of the tool

string

required

Type of the tool

string

Path to tool definition file

string

Description of the tool

json

Additional metadata (JSON format)

string

Import to project after creating

julep tools update --id tool_id \
                  --name "New Name" \
                  --agent-id new_agent_id \
                  --definition new/path/to/config.yaml

The julep tools update command is used to update an existing tool.

string

required

ID of the tool to update

string

New name for the tool

string

New agent ID for the tool

string

Path to new tool definition file

string

New description for the tool

json

New metadata for the tool

julep tools delete --agent-id agent_id --id tool_id [--force]

The julep tools delete command is used to delete an existing tool.

string

required

ID of the agent the tool is associated with

string

required

ID of the tool to delete

boolean

Skip confirmation prompt

julep tools list --agent-id agent_id [--json]

The julep tools list command is used to list all tools for a given agent.

string

Filter by associated agent ID

boolean

Output in JSON format

Execution Management

Create
List
Cancel

julep executions create --task task_id --input '{"key": "value"}'

The julep executions create command is used to create a new execution for a task.

string

required

ID or name of the task to execute

json

JSON string representing the input for the task (defaults to )

string

Path to a file containing the input for the task

julep executions list [--task-id task_id] [--json]

The julep executions list command is used to list all executions or filter based on criteria.

string

Filter executions by associated task ID

boolean

Output the list in JSON format

julep executions cancel --id execution_id

The julep executions cancel command is used to cancel an existing execution.

string

required

ID of the execution to cancel

The CLI will soon include a julep assistant command that launches an interactive prompt for generating commands from plain language. This feature is still under development.

Miscellaneous

Version
Help

julep --version

The julep --version or julep -v command displays the current version of the Julep CLI.

julep --help

The julep --help or julep -h command displays help information for the Julep CLI.

Best Practices

Project Organization

Keep agent, task, and tool definitions in separate directories under src/
Use meaningful file names that reflect their purpose
Follow the standard project structure

Version Control

DO commit julep.yaml to version control
DO commit julep-lock.json to version control
Document project dependencies and requirements

Command Line Usage

Use --json flag for machine-readable output
Use --quiet for scripting and automation
Always provide required parameters

File Management

Project Configuration: Keep your julep.yaml clean and well-organized
Lock File: Use julep-lock.json to track remote state and relationships
Source Files: Organize definitions in appropriate directories under src/

Workflow Tips

Use julep sync regularly to keep local and remote states in sync
Review changes with --json output before applying updates
Use the assistant mode for complex workflows: julep assistant

Security Best Practices

Store API keys securely
Use environment-specific configurations
Review permissions before executing destructive commands
Use --force flags cautiously

Always review the changes before using force flags (--force-local, --force-remote) as they can override remote or local state.

Support

If you need help with further questions in Julep:

Join our Discord community
Check the GitHub repository
Contact support at hey@julep.ai