# Getting Started with the CLI Get up and running with the Zipwire CLI in just a few minutes. ## Installation The Zipwire CLI is published on [npm](https://www.npmjs.com/package/@zipwire/zw) as **`@zipwire/zw`**. You can install it globally with npm, run it once with npx, or build from source. ### Via NPM (Recommended) Install the CLI globally so the `zw` command is available everywhere: ```bash npm install -g @zipwire/zw ``` You need [Node.js](https://nodejs.org/) and npm installed first. The `-g` flag installs the binary globally and adds it to your PATH. After installation, verify it works: ```bash zw --version ``` To upgrade to the latest version later: ```bash npm update -g @zipwire/zw ``` ### Via npx (No Installation) If you prefer not to install globally, you can run the CLI with **npx**. Each run downloads the package if needed: ```bash npx @zipwire/zw --help npx @zipwire/zw activity list npx @zipwire/zw journal track "Quick entry" -d 1h --activity "Company > Project" ``` Useful for trying the CLI or running it in CI without a global install. ### From Source If you have [Go](https://go.dev/) installed and want to build from source: ```bash git clone https://github.com/zipwireapp/zwcli.git cd zwcli go build -o zw ./cmd/zw sudo mv zw /usr/local/bin/ ``` Or install directly with `go install`: ```bash go install github.com/lukepuplett/zwcli/cmd/zw@latest ``` Ensure your Go bin directory (e.g. `~/go/bin`) is on your PATH so the `zw` command is found. See the [CLI repository](https://github.com/zipwireapp/zwcli) for more details. ## Step 1: Authenticate Before you can use the CLI, you need to authenticate with Zipwire. Choose the option that best fits your situation: ### Option A: Sign Up for a New Account (Recommended for New Users) If you don't have a Zipwire account yet, you can sign up directly from the CLI via WhatsApp: ```bash zw auth signup --name "Your Full Name" --whatsapp "+1234567890" ``` Replace the phone number with your WhatsApp number in E.164 format (e.g., +1 for US, +44 for UK). **What happens automatically:** 1. Your API token is stored and ready to use immediately 2. A WhatsApp message from Zipwire's bot arrives with onboarding instructions 3. Follow the bot's prompts in WhatsApp to complete your account activation Once you receive the bot's welcome confirmation in WhatsApp, return to the CLI and start using it—nothing else to do. Your token is already set up and working. 💡 **Tip**: Check your WhatsApp spam folder if you don't see the bot's message immediately. ### Option B: Browser Login (For Existing Users) If you already have a Zipwire account, log in via your browser: ```bash zw auth login ``` This will open your browser automatically, where you can sign in with your passkey or wallet. When complete, your authentication token is saved to `~/.config/zw/config.yaml`. ### Option C: Manual Token If you have an API token, you can set it manually: ```bash zw auth set-token your-api-token ``` ### Check Authentication Status ```bash zw auth status ``` You should see something like: ``` ↓ Authentication status Authenticated Token: zw_... ``` ## Step 2: Your First Command Let's verify everything is working and list your activities: ```bash zw activity list ``` This shows all the activities you've created in Zipwire. Activities follow the structure: `Company > Project > Activity` If you don't have any activities yet, create one: ```bash zw activity create "My Company > First Project > Development" ``` ## Step 3: Track Your First Time Entry Log some time to your journal: ```bash zw journal track "Initial setup and exploration" -d 30m --activity "My Company > First Project > Development" ``` This creates a journal entry with: * Description: "Initial setup and exploration" * Duration: 30 minutes * Activity: "My Company > First Project > Development" View your recent entries: ```bash zw journal list --today ``` ## Accessing Zipwire on the Web Once authenticated, you can generate a magic link to access Zipwire's website without needing to log in again: ```bash zw auth login-link ``` This creates a temporary magic link that you can use in your browser for direct website access. ## What's Next? You now have the basics working! Here's what you can explore: * [**Authentication & Security**](/tools-and-integrations/authentication.md) – Learn about tokens, config files, and security best practices * [**Configuration**](/tools-and-integrations/configuration.md) – Customize your CLI settings * [**Common Workflows**](/tools-and-integrations/workflows.md) – See practical examples (create timesheet, submit for approval, track time, etc.) ## Need Help? The CLI has built-in help for every command: ```bash zw --help # General help zw journal --help # Help for journal commands zw journal track --help # Help for specific command ``` Or explore the [CLI repository](https://github.com/zipwireapp/zwcli) for source code and additional documentation. *** **Pro Tip**: Use `zw --help` frequently. The CLI is self-documenting and often the most up-to-date reference. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.zipwire.io/tools-and-integrations/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.