---
title: Quick Start
description: Shortest path from install to a working AlpacaLoop repository and first managed issue.
relatedCommands:
  - alpaca auth setup --help
  - alpaca init --help
  - alpaca doctor --help
  - alpaca service --help
  - alpaca issue create --help
relatedDocs:
  - install
  - setup
  - issues
  - scheduling
  - service-runtime
  - workflow-state
---

# Quick Start

Use this guide when someone needs the shortest safe route to install AlpacaLoop, connect a repository, create a first managed issue, run one foreground cycle, inspect the result, and then decide whether to enable the service.

## Steps

1. Install the CLI. Use `alpaca docs show install` when Node.js tooling, install source, or development checkout details matter.
2. From the repository root, make sure the tracker CLI or token for the repository provider is available.
3. Sign in at least one worker with `alpaca auth setup`.
4. Run `alpaca init` to create or update `alpaca.config.json`, register the repository, install repo-local Alpaca skill assets, and resolve initial sign-in readiness.
5. Run `alpaca doctor` and fix reported setup, worker, label, or workflow-template problems.
6. Create a managed issue with `alpaca issue create --prompt "<goal>"`. Use `--save-draft` first when the issue should be reviewed before anything is posted to the tracker.
7. Run one foreground cycle with `alpaca run`. To process only the new issue, use `alpaca run --issue <id>` with the tracker issue number.
8. Inspect progress with `alpaca issue list --days 7 --limit 10`, `alpaca issue show --issue <id> --children 1 --limit 5`, and `alpaca issue log show --issue <id> --tail 50`.
9. When foreground runs are understood, enable continuous background polling with `alpaca service enable`, then check `alpaca service status` and `alpaca service log show --tail 50`. On Linux and WSL2, service mode requires a working systemd user session (`systemctl --user`); WSL2 support assumes systemd is enabled. Without that, continue with foreground `alpaca run`.

## Provider Setup

GitHub repositories use `ALPACA_GITHUB_TOKEN` before `alpaca init`, or `gh auth login` for local CLI credentials.

Gitea repositories use `ALPACA_GITEA_USERNAME` and `ALPACA_GITEA_PASSWORD`, or credentials available through Git. `alpaca init --repo-provider gitea` selects Gitea. `--create-repo` is Gitea-only in this version. For a newly created empty Gitea repository, `init` verifies local `HEAD` before remote creation and pushes `HEAD` to the configured base branch; existing repositories are not auto-pushed.

GitLab repositories use `ALPACA_GITLAB_TOKEN` with project access before `alpaca init`. Prefer a token user that can read and update issues, labels, branches, and merge requests for the target project.

## First Issue

For immediate creation:

```bash
alpaca issue create --prompt "Fix flaky login tests."
```

For review before creating:

```bash
alpaca issue create --prompt "Fix flaky login tests." --save-draft
alpaca issue create --apply-draft ~/.alpaca/drafts/.../issue-create-....json
```

For repository workflow setup, bind the issue to the packaged workflow maintenance system workflow and disable side workflows unless explicitly needed:

```bash
alpaca issue create --prompt "Describe this repository's purpose and desired workflow behavior." --workflow __system/workflow-maintenance.md --pr-workflow no_template --unplanned-workflow no_template --followup-proposal off
```

## Watch Outs

- Do not run `alpaca run` while the background service is enabled.
- Run `alpaca service disable` before returning from the background service to manual `alpaca run`.
- The configured remote base branch must exist before creating managed issues or running the service. If setup stopped after creating an empty Gitea repo, recover with `git push <remote> HEAD:<base-branch>` or rerun `alpaca init --base-branch <existing-branch>`.
- `alpaca publish` is not needed before creating a first managed issue. Use it after local repository changes must be finalized and merged to the base branch.
- Normal unscheduled issues receive the `AI: Ready` queue label. Scheduled, recurring, or disabled issue options use different queue labels. Run `alpaca docs show scheduling` before creating delayed or recurring work.

## Related Docs

- `alpaca docs show install`
- `alpaca docs show setup`
- `alpaca docs show issues`
- `alpaca docs show scheduling`
- `alpaca docs show service-runtime`
- `alpaca docs show workflow-state`
