Getting Started with Tangled CLI#

This guide will help you get up and running with the Tangled CLI.

Installation#

Prerequisites#

Rust toolchain 1.70 or later
Git
A Bluesky/AT Protocol account

Build from Source#

Clone the repository:

git clone https://tangled.org/tangled/tangled-cli
cd tangled-cli

Build the project:
```
cargo build --release
```
The binary will be available at target/release/tangled-cli. Optionally, add it to your PATH or create an alias:
```
alias tangled='./target/release/tangled-cli'
```

Install from AUR (Arch Linux)#

If you're on Arch Linux, you can install from the AUR:

yay -S tangled-cli-git

First Steps#

1. Authenticate#

tangled auth login

You'll be prompted for your handle (e.g., alice.bsky.social) and password. If you're using a custom PDS, specify it with the --pds flag:

tangled auth login --pds https://your-pds.example.com

Your credentials are stored securely in your system keyring.

2. Check Your Status#

Verify you're logged in:

tangled auth status

3. List Your Repositories#

See all your repositories:

tangled repo list

Or view someone else's public repositories:

tangled repo list --user alice.bsky.social

4. Create a Repository#

Create a new repository on Tangled:

tangled repo create my-project --description "My awesome project"

By default, repositories are created on the default knot (tngl.sh). You can specify a different knot:

tangled repo create my-project --knot knot1.tangled.sh

5. Clone a Repository#

Clone a repository to start working on it:

tangled repo clone alice/my-project

This uses SSH by default. For HTTPS:

tangled repo clone alice/my-project --https

Working with Issues#

Create an Issue#

tangled issue create --repo my-project --title "Add new feature" --body "We should add feature X"

List Issues#

tangled issue list --repo my-project

View Issue Details#

tangled issue show <issue-id>

Comment on an Issue#

tangled issue comment <issue-id> --body "I'm working on this!"

Working with Pull Requests#

Create a Pull Request#

tangled pr create --repo my-project --base main --head feature-branch --title "Add feature X"

The CLI will use git format-patch to create a patch from your branch.

List Pull Requests#

tangled pr list --repo my-project

Review a Pull Request#

tangled pr review <pr-id> --approve --comment "Looks good!"

Or request changes:

tangled pr review <pr-id> --request-changes --comment "Please fix the tests"

Merge a Pull Request#

tangled pr merge <pr-id>

CI/CD with Spindle#

Spindle is Tangled's integrated CI/CD system.

Enable Spindle for Your Repository#

tangled spindle config --repo my-project --enable

Or use a custom spindle URL:

tangled spindle config --repo my-project --url https://my-spindle.example.com

View Pipeline Runs#

tangled spindle list --repo my-project

Stream Workflow Logs#

tangled spindle logs knot:rkey:workflow-name

Add --follow to tail the logs in real-time.

Manage Secrets#

Add secrets for your CI/CD workflows:

tangled spindle secret add --repo my-project --key API_KEY --value "my-secret-value"

List secrets:

tangled spindle secret list --repo my-project

Remove a secret:

tangled spindle secret remove --repo my-project --key API_KEY

Advanced Topics#

Repository Migration#

Move a repository to a different knot:

tangled knot migrate --repo my-project --to knot2.tangled.sh

This command must be run from within the repository's working directory, and your working tree must be clean and pushed.

Output Formats#

Most commands support JSON output:

tangled repo list --format json

Quiet and Verbose Modes#

Reduce output:

tangled --quiet repo list

Increase verbosity for debugging:

tangled --verbose repo list

Configuration#

The CLI stores configuration in:

Linux: ~/.config/tangled/config.toml
macOS: ~/Library/Application Support/tangled/config.toml
Windows: %APPDATA%\tangled\config.toml

Session credentials are stored securely in your system keyring (GNOME Keyring, KWallet, macOS Keychain, or Windows Credential Manager).

Environment Variables#

TANGLED_PDS_BASE - Override the default PDS (default: https://bsky.social)
TANGLED_API_BASE - Override the Tangled API base (default: https://tngl.sh)
TANGLED_SPINDLE_BASE - Override the Spindle base (default: wss://spindle.tangled.sh)

Troubleshooting#

Keyring Issues on Linux#

If you see keyring errors on Linux, ensure you have a secret service running:

# For GNOME
systemctl --user enable --now gnome-keyring-daemon

# For KDE
# KWallet should start automatically with Plasma

Authentication Failures#

If authentication fails with your custom PDS:

tangled auth login --pds https://your-pds.example.com

Make sure the PDS URL is correct and accessible.

"Repository not found" Errors#

Verify the repository exists and you have access:

tangled repo info owner/reponame

Getting Help#

For command-specific help, use the --help flag:

tangled --help
tangled repo --help
tangled repo create --help

Next Steps#

Explore all available commands with tangled --help
Set up CI/CD workflows with .tangled.yml in your repository
Check out the main README for more examples and advanced usage

Happy collaborating! 🧶