ollama-cli/README.md

Ollama CLI

A comprehensive command-line interface for interacting with Ollama servers, featuring configuration management, profile support, and context persistence.

Installation

Place the ollama script in your PATH and ensure it's executable:

chmod +x ollama
export PATH="$PATH:$(pwd)"

Configuration

The script loads configuration from ~/.ollama/config.json. If the file doesn't exist, it uses built-in defaults.

Configuration File Format

{
  "api_url": "https://ollama-api.example.com/api",
  "user": "ollama",
  "password": "direct_password_here",
  "password_path": "path/to/password/in/pass",
  "default_model": "llama2"
}

Configuration Options:

• api_url: URL to the Ollama API server
• user: Username for API authentication
• password: Direct password (takes precedence over password_path)
• password_path: Path to retrieve password from pass command
• default_model: Default model to use for operations

Environment Variable Overrides

All configuration values can be overridden via environment variables:

• OLLAMA_API_URL_ENV
• OLLAMA_USER_ENV
• OLLAMA_PASS_PATH_ENV
• OLLAMA_PASSWORD_ENV
• DEFAULT_MODEL_ENV

Or use direct variables (lower precedence):

• OLLAMA_API_URL
• OLLAMA_USER
• OLLAMA_PASS_PATH
• OLLAMA_PASSWORD
• DEFAULT_MODEL

Directory Structure

The script maintains the following directories:

• ~/.ollama/context.json - Conversation context for chat (can be overridden with OLLAMA_CONTEXT_FILE)
• ~/.ollama/profiles/ - Profile definitions (can be overridden with OLLAMA_PROFILE_DIR)

Usage

General Help

Usage: ollama <command> [options]

Commands:
  generate <prompt> [options]  Generate a response from a prompt (supports stdin)
  chat [options]               Chat with context memory (supports stdin)
  embed <text> [options]       Generate embeddings for text (supports stdin)
  model <subcommand>           Manage models
  profile <subcommand>         Manage profiles
  version                      Show script and Ollama server version
  help [command]               Show this help message or help for a specific command

For detailed help on a command, run:
  ollama help <command>

Examples:
  ollama help generate
  ollama help chat
  ollama help embed
  ollama help profile
  ollama help model

Environment Variables:
  OLLAMA_CONTEXT_FILE          Override default context file location
  OLLAMA_PROFILE_DIR           Override default profile directory location

Generate Command

Usage: ollama generate <prompt> [options]

Generate a single response from a prompt. Supports reading from stdin.

Options:
  -m, --model MODEL            Use a specific model (default: llama3:8b)
  -p, --profile NAME           Use a profile's system prompt (default: default)

Examples:
  ollama generate "What is 2+2?"
  ollama generate "Write a poem" -m deepseek-r1:8b
  echo "Tell me a joke" | ollama generate
  echo "How do I read a file?" | ollama generate -p python
  ollama generate -p json "List colors"

Chat Command

Usage: ollama chat [options]

Chat with context memory. Maintains conversation history between invocations.

Options:
  -m, --model MODEL            Use a specific model (default: llama3:8b)
  -c, --context FILE           Use a specific context file (default: ~/.ollama/context.json)
  -p, --profile NAME           Use a profile's system prompt (default: default)
  -r, --reset                  Clear the context and start fresh

Examples:
  ollama chat
  echo "Hello!" | ollama chat
  ollama chat -m deepseek-r1:14b
  ollama chat -r                                    # Reset context
  ollama chat -c /tmp/custom_context.json          # Use custom context file
  OLLAMA_CONTEXT_FILE=/tmp/session.json ollama chat  # Use env variable
  ollama chat -p default
  echo "What is Docker?" | ollama chat -p json
  echo "How do I write a loop?" | ollama chat -p python

Embed Command

Usage: ollama embed <text> [options]

Generate embeddings for text using a specified model. Supports reading from stdin.

Options:
  -m, --model MODEL            Use a specific model (default: llama3:8b)
  -p, --profile NAME           Use a profile's model selection (default: default)
  -o, --output FORMAT          Output format: text (default) or json

Output Formats:
  text                         Display embedding summary with first 10 values
  json                         Display full API response including all embedding values

Examples:
  ollama embed "What is machine learning?"
  ollama embed "Hello world" -m nomic-embed-text
  echo "Some text to embed" | ollama embed
  echo "Multiple lines
  of text" | ollama embed -o json
  ollama embed "Search query" -m nomic-embed-text -o json | jq '.embedding | length'

Model Command

Usage: ollama model <subcommand>

Manage and query available models.

Subcommands:
  list                        List all available models with specs
  get MODEL                   Show detailed model information
  ps                          List currently running/loaded models

Examples:
  ollama model list
  ollama model get llama3:8b
  ollama model get deepseek-r1:8b
  ollama model ps

Profile Command

Usage: ollama profile <subcommand> [options]

Manage profiles for system prompts, pre/post scripts, and model selection.

Subcommands:
  list                          List all profile names
  get NAME                      Show profile details
  add NAME PROMPT [OPTIONS]     Create a new profile
  update NAME [PROMPT] [OPTIONS] Update a profile's system prompt or scripts
  delete NAME                   Delete a profile

Profile Options:
  --pre-script SCRIPT           Script to execute on input before sending to ollama
  --post-script SCRIPT          Script to execute on output after receiving from ollama
  -m, --model MODEL             Model to use for this profile

Examples:
  ollama profile list                                    # List all profiles
  ollama profile get json                                # Show profile details
  ollama profile add work "You are a professional..."    # Create profile
  ollama profile add uppercase "Respond in all caps" --pre-script "tr '[:lower:]' '[:upper:]'"
  ollama profile add pretty "Return formatted JSON" --post-script "jq ."
  ollama profile add deep "You are a thinking model" -m deepseek-r1:8b
  ollama profile update python "You are a Python expert..." # Update profile
  ollama profile update json -m gemma:7b-text            # Change model
  ollama profile delete work                             # Delete profile

Version Command

Usage: ollama version [options]

Display the CLI script version and the Ollama server version.

Options:
  -o, --output FORMAT          Output format: text (default) or json

Examples:
  ollama version
  ollama version -o json
  ollama version -o json | jq '.ollama_version'

Requirements

The script requires the following commands to be available:

• curl - Always required
• jq - Always required
• column - Always required
• less - Always required
• pass - Only required if using password_path for authentication

Features

• Configuration Management: Load settings from JSON config file with environment variable overrides
• Multiple Authentication Methods: Direct password, pass integration, or no authentication
• Profiles: Create and manage system prompts with optional pre/post-processing scripts
• Context Persistence: Maintain conversation history across chat invocations
• Flexible Output: Support for both text and JSON output formats
• Stdin Support: Most commands accept input from stdin for easy piping

Version History

• v1.1.0 - Added configuration file support with environment variable overrides
• v1.0.0 - Initial release with version command fix

License

MIT License - See LICENSE.md for details