Articles Command Group

The yt articles command group provides comprehensive management of YouTrack’s knowledge base articles. Articles are documents that can be organized hierarchically and support comments and attachments.

Overview 

YouTrack articles serve as a knowledge base for documentation, guides, and collaborative content. The articles command group allows you to:

Create, edit, and organize articles
Manage article visibility and publishing status
Handle hierarchical article structures (parent-child relationships)
Tag articles for better organization and categorization
Add and manage comments on articles
Handle file attachments
Search and filter articles
Display articles in tree structures

Base Command 

yt articles [OPTIONS] COMMAND [ARGS]...

Article Management Commands 

create 

Create a new article in YouTrack.

yt articles create TITLE [OPTIONS]

Arguments:

TITLE - The title of the article (required)

Options:

Option	Type	Description
`--content, -c`	text	Article content (required if –file not provided)
`--file, -f`	path	Path to markdown file containing article content (required if –content not provided)
`--project-id, -p`	string	Project ID or short name to associate with the article (required)
`--parent-id`	string	Parent article ID for nested articles
`--summary, -s`	string	Article summary (defaults to title)
`--visibility`	choice	Article visibility: public, private, project (default: public)

Examples:

# Create a simple article with inline content
yt articles create "Getting Started Guide" --content "This is a comprehensive guide..." --project-id FPU

# Create an article from a markdown file
yt articles create "Getting Started Guide" --file getting-started.md --project-id FPU

# Create an article in a specific project from a file
yt articles create "API Documentation" --file api-docs.md --project-id FPU

# Create a nested article (child of another article) from a file
yt articles create "Advanced Features" --file advanced.md --parent-id ARTICLE-456 --project-id FPU

# Create a draft article (private visibility) from a file
yt articles create "Draft Article" --file draft.md --visibility private --project-id FPU

# Create an article with inline content (traditional approach)
yt articles create "API Documentation" --content "API usage guide" --project-id FPU

edit 

Edit an existing article’s properties.

yt articles edit ARTICLE_ID [OPTIONS]

Arguments:

ARTICLE_ID - The ID of the article to edit (required)

Options:

Option	Type	Description
`--title, -t`	string	New article title
`--content, -c`	string	New article content
`--summary, -s`	string	New article summary
`--visibility`	choice	New visibility level: public, private, project
`--show-details`	flag	Show detailed article information

Examples:

# Update article title
yt articles edit ARTICLE-123 --title "Updated Title"

# Update article content
yt articles edit ARTICLE-123 --content "Updated content"

# Change visibility
yt articles edit ARTICLE-123 --visibility public

# View detailed article information
yt articles edit ARTICLE-123 --show-details

publish 

Publish a draft article (change from private to public visibility).

yt articles publish ARTICLE_ID

Arguments:

ARTICLE_ID - The ID of the draft article to publish (required)

Examples:

# Publish a draft article
yt articles publish ARTICLE-123

Article Listing and Discovery 

list 

List articles with filtering and formatting options.

yt articles list [OPTIONS]

Options:

Option	Type	Description
`--project-id, -p`	string	Filter by project ID
`--parent-id`	string	Filter by parent article ID
`--fields, -f`	string	Comma-separated list of fields to return
`--top, -t`	integer	Maximum number of articles to return
`--query, -q`	string	Search query to filter articles
`--format`	choice	Output format: table, json (default: table)

Examples:

# List all articles
yt articles list

# List articles in table format (default)
yt articles list --format table

# List articles in JSON format
yt articles list --format json

# Filter articles by project
yt articles list --project-id PROJECT-123

# Filter articles by parent
yt articles list --parent-id ARTICLE-456

# Limit number of articles returned
yt articles list --top 20

tree 

Display articles in hierarchical tree structure showing parent-child relationships.

yt articles tree [OPTIONS]

Options:

Option	Type	Description
`--project-id, -p`	string	Filter by project ID
`--fields, -f`	string	Comma-separated list of fields to return
`--top, -t`	integer	Maximum number of articles to return

Examples:

# Display articles in hierarchical tree structure
yt articles tree

# Filter tree view by project
yt articles tree --project-id PROJECT-123

search 

Search articles using full-text search.

yt articles search QUERY [OPTIONS]

Arguments:

QUERY - Search query string (required)

Options:

Option	Type	Description
`--project-id, -p`	string	Filter by project ID
`--top, -t`	integer	Maximum number of results to return
`--format`	choice	Output format: table, json (default: table)

Examples:

# Search articles
yt articles search "getting started"

# Search articles in a specific project
yt articles search "API" --project-id PROJECT-123

# Limit search results
yt articles search "documentation" --top 10

draft 

List and manage draft articles (unpublished articles that do not have unlimited visibility).

yt articles draft [OPTIONS]

Options:

Option	Type	Description
`--project-id, -p`	string	Filter by project ID
`--format`	choice	Output format: table, json (default: table)

Examples:

# List draft articles
yt articles draft

# Filter drafts by project
yt articles draft --project-id PROJECT-123

sort 

Display child articles under a parent article in sorted order for visualization.

yt articles sort PARENT_ID [OPTIONS]

Note: This command displays articles in sorted order for reference only. Article reordering in YouTrack requires manual drag-and-drop in the web interface due to API limitations (the ordinal field is read-only).

API Limitation Notice: The YouTrack API does not support programmatic article reordering. Please upvote this feature request to help prioritize API support: https://youtrack.jetbrains.com/issue/JT-79905/Allow-sorting-Knowledge-Base-articles-alphabetically

Arguments:

PARENT_ID - The ID of the parent article (required)

Options:

Option	Type	Description
`--sort-by`	choice	Sort child articles by title, creation date, or update date for display (choices: title, created, updated; default: title)
`--reverse`	flag	Reverse the sort order

Examples:

# Display child articles sorted by title (default)
yt articles sort PARENT-ARTICLE-123

# Display child articles sorted by creation date
yt articles sort PARENT-ARTICLE-123 --sort-by created

# Display child articles sorted by title in reverse order
yt articles sort PARENT-ARTICLE-123 --reverse

# Display child articles sorted by update date in reverse order
yt articles sort PARENT-ARTICLE-123 --sort-by updated --reverse

API Limitations:

YouTrack’s REST API does not support programmatic article reordering. The ordinal field that controls article position is read-only. To reorder articles, use YouTrack’s web interface with drag-and-drop functionality.

Please upvote this feature request to help prioritize API support: https://youtrack.jetbrains.com/issue/JT-79905/Allow-sorting-Knowledge-Base-articles-alphabetically

Tag Management 

tag 

Add tags to an article for better organization and categorization.

yt articles tag ARTICLE_ID [TAG_NAME1] [TAG_NAME2] ...

Arguments:

ARTICLE_ID - The ID of the article to tag (required)
TAG_NAME - Names of tags to add (optional, if not provided shows interactive selection)

Interactive Mode:

When no tag names are provided, the command enters interactive mode where you can:

View all available tags in the system
Select multiple tags using numbered indices
Confirm your selection before applying

Examples:

# Add specific tags to an article
yt articles tag ARTICLE-123 bug documentation

# Interactive tag selection (shows all available tags)
yt articles tag ARTICLE-123

# Add a single tag
yt articles tag ARTICLE-123 urgent

Interactive Mode Usage:

🔍 Fetching available tags...

📋 Available tags:
  1. bug (ID: 1-0)
  2. documentation (ID: 2-0)
  3. feature (ID: 3-0)
  4. urgent (ID: 4-0)
  5. review (ID: 5-0)

💡 Enter tag numbers separated by spaces (e.g., 1 3 5) or 'q' to quit:
1 2 4

🏷️  Selected tags: bug, documentation, urgent
🔄 Adding tags to article ARTICLE-123...
✅ Successfully added 3 tags to article ARTICLE-123

Features:

Tag Name Matching: When providing tag names directly, the command performs case-insensitive matching
Interactive Selection: Shows all available tags with their IDs for easy selection
Multi-select: Can apply multiple tags in a single operation
Validation: Validates that tags exist before applying them
Error Handling: Provides clear feedback for invalid tags or articles

Comment Management 

comments add 

Add a comment to an article.

yt articles comments add ARTICLE_ID TEXT

Arguments:

ARTICLE_ID - The ID of the article (required)
TEXT - The comment text (required)

Examples:

# Add a comment to an article
yt articles comments add ARTICLE-123 "This is a helpful article!"

comments list 

List comments on an article.

yt articles comments list ARTICLE_ID [OPTIONS]

Arguments:

ARTICLE_ID - The ID of the article (required)

Options:

Option	Type	Description
`--format`	choice	Output format: table, json (default: table)

Examples:

# List comments on an article
yt articles comments list ARTICLE-123

# List comments in JSON format
yt articles comments list ARTICLE-123 --format json

comments update 

Update an existing comment (not yet implemented).

yt articles comments update COMMENT_ID TEXT

Arguments:

COMMENT_ID - The ID of the comment (required)
TEXT - The new comment text (required)

Note

This functionality is not yet implemented and requires additional API endpoints.

comments delete 

Delete a comment (not yet implemented).

yt articles comments delete COMMENT_ID [OPTIONS]

Arguments:

COMMENT_ID - The ID of the comment to delete (required)

Options:

Option	Type	Description
`--confirm`	flag	Skip confirmation prompt

Note

This functionality is not yet implemented and requires additional API endpoints.

Attachment Management 

attach list 

List attachments for an article.

yt articles attach list ARTICLE_ID [OPTIONS]

Arguments:

ARTICLE_ID - The ID of the article (required)

Options:

Option	Type	Description
`--format`	choice	Output format: table, json (default: table)

Examples:

# List attachments for an article
yt articles attach list ARTICLE-123

# List attachments in JSON format
yt articles attach list ARTICLE-123 --format json

attach upload 

Upload a file to an article (not yet implemented).

yt articles attach upload ARTICLE_ID FILE_PATH

Arguments:

ARTICLE_ID - The ID of the article (required)
FILE_PATH - Path to the file to upload (required)

Note

This functionality is not yet implemented and requires multipart form upload implementation.

attach download 

Download an attachment from an article (not yet implemented).

yt articles attach download ARTICLE_ID ATTACHMENT_ID [OPTIONS]

Arguments:

ARTICLE_ID - The ID of the article (required)
ATTACHMENT_ID - The ID of the attachment (required)

Options:

Option	Type	Description
`--output, -o`	path	Output file path

Note

This functionality is not yet implemented and requires binary file handling.

attach delete 

Delete an attachment from an article (not yet implemented).

yt articles attach delete ARTICLE_ID ATTACHMENT_ID [OPTIONS]

Arguments:

ARTICLE_ID - The ID of the article (required)
ATTACHMENT_ID - The ID of the attachment to delete (required)

Options:

Option	Type	Description
`--confirm`	flag	Skip confirmation prompt

Note

This functionality is not yet implemented and requires additional API endpoints.

Article Features 

Hierarchical Organization

Articles support parent-child relationships, allowing you to create structured documentation with nested sections.

Visibility Control

Articles can have different visibility levels:

public - Visible to all users
private - Visible only to the author (draft mode)
project - Visible to project members only

Rich Content Support

Articles support rich text content including formatting, links, and embedded content.

Collaboration

Comments allow team members to collaborate on articles and provide feedback.

File Attachments

Articles can have file attachments for additional resources and documentation.

Search and Discovery

Full-text search capabilities make it easy to find relevant articles across your knowledge base.

Common Workflows 

Creating Documentation Structure 

# Create main documentation article
yt articles create "Project Documentation" --content "Main documentation hub" --project-id FPU

# Create child articles
yt articles create "Getting Started" --content "How to get started" --parent-id MAIN-ARTICLE-ID
yt articles create "API Reference" --content "API documentation" --parent-id MAIN-ARTICLE-ID
yt articles create "Troubleshooting" --content "Common issues" --parent-id MAIN-ARTICLE-ID

# View the documentation tree
yt articles tree --project-id FPU

Draft to Publication Workflow 

# Create a draft article
yt articles create "New Feature Guide" --content "Draft content" --visibility private --project-id FPU

# Edit and refine the draft
yt articles edit ARTICLE-123 --content "Updated draft content"

# Publish when ready
yt articles publish ARTICLE-123

Content Management 

# Search for articles to update
yt articles search "outdated"

# Update article content
yt articles edit ARTICLE-123 --content "Updated content for 2024"

# Add comments for collaboration
yt articles comments add ARTICLE-123 "Please review the updated content"

# View article details
yt articles edit ARTICLE-123 --show-details

# Tag articles for better organization
yt articles tag ARTICLE-123 documentation tutorial

Working with Markdown Files 

# Create articles from existing markdown files
yt articles create "Installation Guide" --file docs/installation.md --project-id FPU

# Create multiple articles from markdown files
yt articles create "User Manual" --file user-manual.md --project-id FPU
yt articles create "Developer Guide" --file dev-guide.md --project-id FPU

# Organize markdown documentation into YouTrack articles
for file in docs/*.md; do
    title=$(basename "$file" .md)
    yt articles create "$title" --file "$file" --project-id FPU
done

Best Practices 

Use Hierarchical Structure: Organize articles in a logical hierarchy using parent-child relationships.
Clear Titles: Use descriptive titles that make articles easy to find and understand.
Draft First: Create articles as drafts (private visibility) to refine content before publishing.
Regular Updates: Keep articles current by regularly reviewing and updating content.
Leverage Comments: Use comments for collaboration and feedback on article content.
Project Organization: Associate articles with relevant projects for better organization.
Search Optimization: Use clear, searchable content to make articles discoverable.
Consistent Formatting: Follow consistent formatting and style guidelines across articles.
Use Markdown Files: For complex content, consider writing in markdown files first and using the --file option for better version control and editing experience.

Error Handling 

Common error scenarios and solutions:

Permission Denied: Ensure you have appropriate permissions to create, edit, or view articles in the specified project.
Article Not Found: Verify the article ID exists and you have access to view it.
Invalid Parent ID: Check that the parent article ID exists and you have permission to create child articles.
Visibility Restrictions: Ensure you have appropriate permissions for the specified visibility level.
Content Too Large: YouTrack may have limits on article content size. Consider breaking large articles into smaller sections.
File Not Found: Ensure the file path provided with --file exists and is accessible.
Invalid File Content: The specified file must be a valid text file. Binary files or files with invalid encoding will be rejected.
Empty File: Files provided with --file must contain content. Empty files will be rejected.
Both Content and File Specified: You cannot use both --content and --file options simultaneously. Choose one method for providing article content.