CLI Commands

Complete reference for all Gyrus CLI commands.

Global Options

These options work with all commands:

Option	Description
--workspace <name>	Target a specific workspace instead of the default
--help	Show help for a command
--version	Show version number

Commands

gyrus init

Initialize a new workspace.

gyrus init [path] [options]

Arguments:

Argument	Default	Description
path	~/gyrus	Directory path for the workspace

Options:

Option	Description
--name <name>	Workspace name (defaults to directory name)
--description <desc>	Human-readable description

Examples:

# Initialize default workspace
gyrus init

# Initialize with custom path and name
gyrus init ~/work/brain --name work --description "Work projects"

# Initialize in current directory
gyrus init ./brain --name myproject

---

gyrus workspaces

List all registered workspaces.

gyrus workspaces
gyrus ws  # alias

Output:

Workspaces:
  * personal    ~/gyrus                Personal knowledge
    work        ~/work/brain           Work projects

The * indicates the default workspace.

---

gyrus use

Set the default workspace.

gyrus use <name>

Arguments:

Argument	Required	Description
name	Yes	Name of workspace to set as default

Examples:

gyrus use work
gyrus use personal

---

gyrus doctor

Run diagnostics and health checks.

gyrus doctor [options]

Options:

Option	Description
--workspace <name>	Check a specific workspace
--all	Check all workspaces

Checks performed:

• Configuration file exists and is valid
• Workspace directories exist and are accessible
• Required folders (knowledge/, adrs/) are present
• File permissions are correct

Examples:

# Check default workspace
gyrus doctor

# Check specific workspace
gyrus doctor --workspace work

# Check all workspaces
gyrus doctor --all

---

gyrus mcp

Start the MCP server for AI agent integration.

gyrus mcp [options]

Options:

Option	Description
--workspace <name>	Initial workspace context

The MCP server uses stdio transport for communication with AI agents.

Example configuration for Claude Desktop:

{
  "mcpServers": {
    "gyrus": {
      "command": "gyrus",
      "args": ["mcp"]
    }
  }
}

---

gyrus serve

Start the dashboard web server.

gyrus serve [options]

Coming Soon

This command is not yet implemented.

Options:

Option	Default	Description
--port <number>	3333	Port to listen on

---

gyrus daemon

Start HTTP/SSE MCP server for network access.

gyrus daemon [options]

Coming Soon

This command is not yet implemented.

Options:

Option	Default	Description
--port <number>	3334	Port to listen on

---

Skill Commands

gyrus skill list

List all skills.

gyrus skill list [options]
gyrus s list  # alias

Options:

Option	Description
--workspace <name>	Target workspace
--tags <t1,t2,...>	Filter by tags

---

gyrus skill read

Read a specific skill.

gyrus skill read <name> [options]
gyrus s read <name>  # alias

Arguments:

Argument	Required	Description
name	Yes	Skill name to read

Options:

Option	Description
--workspace <name>	Target workspace

---

gyrus skill search

Search skills.

gyrus skill search <query> [options]
gyrus s search <query>  # alias

Arguments:

Argument	Required	Description
query	No	Text to search for

Options:

Option	Description
--workspace <name>	Target workspace
--tags <t1,t2,...>	Filter by tags
--trigger <pattern>	Filter by trigger pattern

---

gyrus skill create

Create a new skill.

gyrus skill create [options]
gyrus s create  # alias

Options:

Option	Required	Description
--name <name>	Yes	Skill name in kebab-case
--title <title>	Yes	Human-readable title
--content <content>	Yes*	Skill content
--file <path>	Yes*	Read content from file
--workspace <name>	No	Target workspace
--description <desc>	No	Brief description
--tags <t1,t2,...>	No	Tags (comma-separated)
--triggers <t1,t2,...>	No	Triggers (comma-separated)
--apply-to <p1,p2,...>	No	File patterns (comma-separated)
--related <n1,n2,...>	No	Related skill names

*Either --content or --file is required.

Examples:

# Create with inline content
gyrus skill create \
  --name code-review \
  --title "Code Review Guide" \
  --content "# Code Review\n\nWhen reviewing..."

# Create from file
gyrus skill create \
  --name api-design \
  --title "API Design Guidelines" \
  --file ./guidelines.md \
  --tags api,design

---

gyrus skill update

Update an existing skill.

gyrus skill update <name> [options]
gyrus s update <name>  # alias

Arguments:

Argument	Required	Description
name	Yes	Skill name to update

Options:

Option	Description
--workspace <name>	Target workspace
--title <title>	New title
--content <content>	New content
--file <path>	Read new content from file
--description <desc>	New description
--tags <t1,t2,...>	New tags (replaces existing)
--triggers <t1,t2,...>	New triggers (replaces existing)
--apply-to <p1,p2,...>	New file patterns (replaces existing)
--related <n1,n2,...>	New related skills (replaces existing)

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Workspace not found

Environment Variables

Variable	Description
GYRUS_CONFIG	Override config file location (default: ~/.config/gyrus/config.json)
GYRUS_DEFAULT_WORKSPACE	Override default workspace

Configuration File

The global configuration is stored at ~/.config/gyrus/config.json:

{
  "version": 1,
  "default": "personal",
  "workspaces": [
    {
      "name": "personal",
      "path": "~/gyrus",
      "description": "Personal knowledge"
    }
  ],
  "settings": {
    "serve": { "port": 3333 },
    "daemon": { "port": 3334 }
  }
}

See Also

• Getting Started — First-time setup guide
• Workspaces — Managing multiple workspaces
• Skills — Reusable AI instructions
• MCP Integration — AI agent integration