> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amika.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Programmatic usage

> Script the Amika CLI to spin up a rig, drive an agent non-interactively, and ship the result.

The Amika CLI is shell-friendly, so you can wire it into bash scripts, CI jobs,
and code-gen pipelines. This guide walks through a complete automated flow:
push a credential, create a remote rig cloned from a git repo, drive Claude
Code non-interactively to make a change and open a PR, then tear the rig
down.

## Prerequisites

* The CLI installed and logged in. See [Install](https://docs.amika.dev/install.md) and
  [Authentication](https://docs.amika.dev/reference/auth.md).
* A Claude API key on disk. See
  [Manage secrets](https://docs.amika.dev/guides/manage-secrets.md) for how to push it to
  the Amika secrets store.
* Run from inside a git repository whose remote you want the agent to work
  against.

> [!NOTE]
>
> The pattern below uses `amika rig ssh` with heredocs to control the agent.
> Pair it with `--agent-credential-type` so the right credential is injected
> without an interactive picker. See
> [Inject credentials](https://docs.amika.dev/guides/inject-credentials.md).

## Walkthrough

**1. Push your Claude API key to the Amika vault**

```bash theme={null}
amika secret claude push \
  --type api_key \
  --from-file /path/to/your/CLAUDE_API_KEY
```

`--from-file` reads the key without prompting, which keeps the script
non-interactive.

**2. Create a remote rig cloned from the repo**

```bash theme={null}
amika rig create \
  --agent-credential-type claude=api-key \
  --name testing-claude-api
```

Running the command inside a Git repository selects that repository.
`--agent-credential-type claude=api-key` tells Amika to inject your stored
API-key credential, which avoids the OAuth picker.

**3. Configure agent permissions inside the rig**

Use a heredoc with `amika rig ssh` to write a Claude
`settings.local.json`. The `$AMIKA_AGENT_CWD` env var resolves to the cloned
repo root inside the rig.

```bash theme={null}
export CLAUDE_SETTINGS='
{
    "permissions": {
        "allow": [
            "Bash(git:*)",
            "Bash(gh:*)"
        ]
    }
}'

amika rig ssh testing-claude-api << EOF
mkdir -p \$AMIKA_AGENT_CWD/.claude
echo 'settings.local.json' > \$AMIKA_AGENT_CWD/.claude/.gitignore
echo '$CLAUDE_SETTINGS' > \$AMIKA_AGENT_CWD/.claude/settings.local.json
EOF
```

The unquoted `<< EOF` lets the host shell expand `$CLAUDE_SETTINGS` before
ssh transmits the body. Guest-side variables like `$AMIKA_AGENT_CWD` are
escaped with `\$` so they survive to the rig shell and resolve there.

These permissions let the agent run `git` and `gh` commands. Adjust the
allowlist to match what your script needs.

**4. Generate a session id so you can resume the agent run**

```bash theme={null}
export CLAUDE_UUID=$(uuidgen)
```

Holding the session id lets you continue the same conversation across multiple
agent invocations. This is useful when you want to break the work into phases.

**5. Run Claude non-interactively to make code changes**

```bash theme={null}
export CLAUDE_PROMPT="Change the heading text to also include, 'Dylan was here!'

Do not stop, do not ask me for clarification or questions.
"

amika rig ssh -t testing-claude-api << EOF
cd \$AMIKA_AGENT_CWD && claude \
  --dangerously-skip-permissions \
  --session-id '$CLAUDE_UUID' \
  -p '$CLAUDE_PROMPT' < /dev/null
EOF
```

A few details that matter for scripting:

* `-t` allocates a TTY so Claude renders correctly.
* `--dangerously-skip-permissions` is safe here because the allowlist in
  `settings.local.json` already constrains what the agent can do.
* `< /dev/null` closes stdin so Claude exits when the prompt is done instead of
  waiting for input.

**6. Resume the same session to commit and open a PR**

```bash theme={null}
amika rig ssh -t testing-claude-api << EOF
cd \$AMIKA_AGENT_CWD && claude \
  --dangerously-skip-permissions \
  --resume '$CLAUDE_UUID' \
  -p 'Make a git branch and commit the changes. Then make a Github PR' < /dev/null
EOF
```

Splitting the code change and the git/PR work into two prompts is more
reliable than asking the agent to do both at once.

**7. Tear down the rig**

```bash theme={null}
amika rig rm --force testing-claude-api
```

`--force` skips the confirmation prompt, which is what you want in a script.

## Full script

Drop this into a file and run it end-to-end. Make sure
`/path/to/your/CLAUDE_API_KEY` exists and that GitHub access is set up in
[GitHub settings](https://app.amika.dev/settings/github) so the agent can
push the branch and open the PR. See
[GitHub authentication](https://docs.amika.dev/guides/github-authentication.md).

```bash theme={null}
#!/bin/bash
set -euo pipefail

errcho() { echo "$@" >&2; }

amika secret claude push \
  --type api_key \
  --from-file /path/to/your/CLAUDE_API_KEY

errcho "Creating rig..."
amika rig create \
  --agent-credential-type claude=api-key \
  --name testing-claude-api

export CLAUDE_SETTINGS='
{
    "permissions": {
        "allow": [
            "Bash(git:*)",
            "Bash(gh:*)"
        ]
    }
}'

errcho "Configuring Claude settings in rig..."
amika rig ssh testing-claude-api << EOF
mkdir -p \$AMIKA_AGENT_CWD/.claude
echo "settings.local.json" > \$AMIKA_AGENT_CWD/.claude/.gitignore
echo '$CLAUDE_SETTINGS' > \$AMIKA_AGENT_CWD/.claude/settings.local.json
EOF

export CLAUDE_UUID=$(uuidgen)
export CLAUDE_PROMPT="Change the heading text to also include, 'Dylan was here!'

Do not stop, do not ask me for clarification or questions.
"

errcho "Running Claude to make code changes..."
amika rig ssh -t testing-claude-api << EOF
cd \$AMIKA_AGENT_CWD && claude --dangerously-skip-permissions --session-id '$CLAUDE_UUID' -p '$CLAUDE_PROMPT' < /dev/null
EOF

errcho "Resuming Claude to create git branch and PR..."
amika rig ssh -t testing-claude-api << EOF
cd \$AMIKA_AGENT_CWD && claude --dangerously-skip-permissions --resume '$CLAUDE_UUID' -p 'Make a git branch and commit the changes. Then make a Github PR' < /dev/null
EOF

errcho "Removing rig..."
amika rig rm --force testing-claude-api
```

> [!TIP]
>
> For long agent runs, drop `set -e` around the agent invocations or wrap them
> so a single failed run does not leak a rig. `amika rig rm --force`
> should always run, even on failure.

## Next steps

> [card] [Inject credentials](https://docs.amika.dev/guides/inject-credentials.md)
>
> Push and pin Claude or Codex credentials for rigs.

> [card] [CLI reference](https://docs.amika.dev/reference/cli.md)
>
> Full flag listings for rig, secret, and ssh commands.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.